With rustdoc, it is possible to write documentation for private items, which won't be rendered unless the --document-private-items flag is passed.
/// Does the thing.
fn do_the_thing() {}
Sometimes, I want to describe the internals of a public item, but not necessarily render them for users of my library.
/// Does the thing.
///
/// We rely on the fact that the other thing is
/// red if and only if it rained yesterday, i.e.
///
/// ```
/// assert!(true);
/// ```
///
/// ...but this is not actually relevant to
/// anyone using this library.
pub fn do_the_thing() {}
This is not the same as simple // comments, for two reasons:
Trivially, because just like for private items, I'd like to see the documentation rendered
I want to illustrate the internals with examples, and I want them to be tested
Is this possible? Is it useful? or am I missing something? Where is the relevant source code? Where can I send mail/patches or submit issues/PRs?
It seems like a very narrow use case. If something is useful to users of the function, it should be documented. If it's not for users, but for implementors, then it may as well be in the source code.
You can also make the public function a thin wrapper for a private function, and have private docs on the private function.
That argument applies to rendered documentation for private items too. But I acknowledge that the use case is narrow. It boils down to whether rendered documentation for contributors adds any value to the source code.
I would argue that it does. Not necessarily because of the rendering, or because of testing in-context examples, but because it encourages extensively documenting internals (rustdoc is certainly one of the reasons why Rust code is so well documented). It's helpful to contributors --- if you know what some code is supposed to do, then it is much easier to understand. I think that making code maintainable by other programmers is very important, especially in the long term.