I've gotten into the habit of writing rustdoc even for the private items in my projects. With cargo doc --document-private-items, it yields very helpful guides for internal contributors. When I added a few example block doctests, though, I ended up stubbing my toe on a couple related corners:
The context of a doctest is external to the crate it is documenting, therefore private items are not visible
cargo test tries to build and run doctests, even in private items
This leaves me with several options, none of which are very satisfying:
Make the items I want to document public, even though they should not be used by downstream code
Mark examples in private items as ```ignore, leaving them untested and cluttering cargo test output
Just not write examples
Are there some other options I should consider here?
Would it be feasible to have doctests interpreted as an internal module?
It does seem that it would make sense that examples for private APIs could reference other private APIs.
Since --document-private-items doesn't show any notice of public/private items (the assumption is that the docs are rendered for internal use only), would it make sense to do the test build with every symbol exposed as public? @ doc-team
The problem is that doc tests are ran as "integration tests", where they have access to your code as an external crate. For private items, it makes more sense for the documentation test to be a #[test] fn inline next to it.
The way I see it, the current system pretty much isn't built for documenting private items.
This is very unfortunate, because it gives off the impression that documenting private items in Rust is discouraged (which I hope is not true, as documentation is very valuable to contributors), and therefore makes new users confused when they try to document private items.
I see it as the major problem with the tooling that Cargo provides.
The way I would imagine this to work is the following:
Any item visible to the module the documented item is in, would also be visible to the corresponding test.
I think, that it's not the best idea to have everything visible to a doctest. The reason for this is, that a doctest should document the thing it's attached to, not any other code, and it's almost always the case that all related code to an item is visible to it.
