Is is possible to generate documentation for one private function?

Question

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.

Answer 1

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`?.