3

How can I force rustdoc documentation for one private function?

In my project, there are many private functions. I do not want them to be part of the generated rustdoc output (command cargo doc). It's unnecessary for library users to read about these private functions. However, there is one private function that should be part of the generated rustdoc output. Explaining this one private function will help library users understand the entire rust library. But still, I do not want users to call this function directly (hence private).

I know there is a command-line option --document-private-items but I do not want documentation for the many other private functions.

Is there an attribute or command-line switch to force documentation generated for this one private function? I was hoping for a contrary attribute to #[doc(hidden)], like #[doc(force)], or #[doc(show)], or #[not(doc(hidden))], etc.

kmdreko
  • 42,554
  • 6
  • 57
  • 106
JamesThomasMoon
  • 6,169
  • 7
  • 37
  • 63
  • 1
    I do not think that is currently possible due to [this open issue](https://github.com/rust-lang/rust/issues/66528). – frankenapps Aug 11 '22 at 08:37
  • Thanks @frankenapps . I left comment at https://github.com/rust-lang/rust/issues/60884#issuecomment-1212480451 – JamesThomasMoon Aug 11 '22 at 20:51
  • "*Explaining this one private function will help library users understand the entire rust library*" This sounds like front page or module documentation, without specifically referencing the private method. It feels like an [XY Problem](https://meta.stackexchange.com/questions/66377/what-is-the-xy-problem). More detail about the situation would help. – Schwern Sep 08 '22 at 03:57
  • Thanks @Schwern, "XY Problem" interesting link! I have solved the problem with what you recommended; adding documentation at the module-level. But I'm curious about the larger problem/need in rust documentation; allowing selective documentation for things typically excluded from documention (most often private functions). – JamesThomasMoon Sep 08 '22 at 05:33
  • 1
    That's what the free-form docs are for. Private functions are hidden from the user because they might change at any time. If you document them, they are part of the published interface, a promise to the user, and should be public. Martin Fowler has written about the importance of ["published vs private"](https://www.martinfowler.com/bliki/PublishedInterface.html). – Schwern Sep 08 '22 at 15:42

1 Answers1

2

Displaying a private item in public documentation seems misguided. Such documentation would likely entice users to attempt using it even if there were sign-posting saying otherwise. The appropriate place to document crate internals that might still be useful for outsiders to know would be:

  • crate-level documentation
  • module-level documentation (can be a dummy module like snafu::guide)
  • repository docs/ folder (less visible but another place to check)

A slightly different motivator would be to document items that normal users shouldn't use, but nevertheless must be public for advanced users to use. If that were the case, I'd suggest adding an "expert" feature flag to your crate to indicate such items should be used with caution and understanding. Check out How to get a feature requirement tag in the documentation generated by `cargo doc`?.

kmdreko
  • 42,554
  • 6
  • 57
  • 106