I find rustdoc lacking for clap. rustdoc does a good job with API reference documentation and is improving in its handling of examples but derive reference and

I find rustdoc lacking for clap. rustdoc does a good job with API reference documentation and is improving in its handling of examples but derive reference and tutorial documentation are a weak point. For examples, its improving with the example scraping work (e.g. https://docs.rs/clap/latest/clap/struct.ArgMatches.html#method.value_of https://docs.rs/clap/latest/clap/struct.ArgMatches.html#meth...) but testing of example is still lacking. I've written trycmd to help (https://github.com/assert-rs/trycmd https://github.com/assert-rs/trycmd). For derive reference and tutorial documentation, your choices are - A very long, hard to navigate top-level documentation, see https://docs.rs/structopt/latest/structopt/ https://docs.rs/structopt/latest/structopt/ - External documentation, see https://serde.rs/ https://serde.rs/ - Dummy modules to store your documentation (I've seen this used but can't remember one off the top of my head) For clap, my documentation examples are best served as programs and we've had a problem with these being broken. The Rust CLI book has a decent strategy for this by pulling in code from external files (https://rust-cli.github.io/book/index.html https://rust-cli.github.io/book/index.html). I was tempted to do that for clap where example code and output (all verified via trycmd) are pulled into an mdbook site but I've stopped short and just have a README that links out to everything (https://github.com/clap-rs/clap/blob/master/examples/tutorial_derive/README.md https://github.com/clap-rs/clap/blob/master/examples/tutoria...). Its not great.