Rustdoc --dev-dependencies, --tests, --all-targets

tools and infrastructure
1

We have cargo check --all-targets which checks everything in-tree (excluding doctests but, AIUI, including #[test] and cargo "integration" tests).

But cargo doc is more limited. Limitations seem to me to include:

  • No ability to document test items at all. This could be a hindrance when a package has sophisticated test suite with infrastructure which is all #[cfg(test)]
  • No command line option like --all-targets to bring together all the things that can be documented.
  • The way to get dev-dependencies documented is to say --examples. This is rather obscure. It also has a downside: examples often have short name-clashy kinds of names, and this interacts badly with the cargo output file name clash problem (https://github.com/rust-lang/cargo/issues/6313 etc). There is no way to document dev-dependencies?

I suggest the following approach:

  • Introduce a new --document-dev-dependencies option (name TBD) which adds the dev-dependencies to the things to be documented. This can be stable as soon as it is implemented, and provides a way to get the dev-dependencies documented without being afflicted by the cargo output dupes problem.
  • Introduce a new unstable option --all-targets which documents everything that can be documented.
  • Change cargo's output paths for examples, placing all examples into a path derived from the containing package and the path within the module.
  • Provide --tests which documents (only, all) tests. For cargo "integration" tests, the output filename should be very qualified, like for examples.
  • When all of the above is done, --all-targets actually does document all tagets and can be stabilised.
1 Like
2

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