Developer Documentation

tools and infrastructure
1

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):

  1. Generating developer documentation is not straightforward (see #15347)
  2. 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:

  1. cargo doc generating target/doc and target/devdoc
  2. cargo test running 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?

1 Like
2

Why not default to generating dev docs for the package you’re working on, and non-dev docs for dependencies?

As for tests, I wonder if it’d be possible to just have tests have “adopted” visibility.

3

I created a thread in the users forum some days ago about it too. I think it’s an important feature that could help development a lot.

4

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.