While the workflow for writing user documentation (documentation for public types) for rust libraries is already paved, explained and supported, there are still problems for writing developer documentation (documentation for private types).
Currently I see two problems (though I probably haven’t been far enough down the rabbit hole):
- Generating developer documentation is not straightforward (see #15347)
- Examples for private types are tested in the same way as examples for public types, causing obvious visibility issues (see #30094)
While 1. only is a minor imperfection, 2. limits the way developer documentation can be written. Having tested examples is necessary for both user and developer documentation.
Ideas to fix these issues: (please keep in mind that I have no experience regarding the inner workings of rustc, rust doc or cargo test)
My aim: Support both user documentation and developer documentation equally well. Emphasize the difference. Make having a developer documentation the default. Do that by:
cargo docgenerating target/doc and target/devdoc
cargo testrunning tests for public type examples as before. Run tests for private types inside their module by default.
What are your thoughts on that issue? Am I to radical in my conclusions? Are there workarounds I am not aware of?