4

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.

Improve this question
5
  • 1
    I do not think that is currently possible due to this open issue. Commented Aug 11, 2022 at 8:37
  • Thanks @frankenapps . I left comment at github.com/rust-lang/rust/issues/60884#issuecomment-1212480451 Commented Aug 11, 2022 at 20:51
  • 1
    "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. More detail about the situation would help. Commented Sep 8, 2022 at 3: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). Commented Sep 8, 2022 at 5: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". Commented Sep 8, 2022 at 15:42

1 Answer 1

Reset to default
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`?.

Improve this answer
Sign up to request clarification or add additional context in comments.

Comments

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.