cargo-public-api VS snapbox

The API diffing tool already exists ;) Check out https://github.com/Enselic/cargo-public-api ! Would be super cool to integrate with diff.rs at some point. Nice job with diff.rs btw!

You might also enjoy https://github.com/Enselic/cargo-public-api -- would be great with a precommit or CI hook that prevents one from accidentally removing/changing public API.

The CI story will become a bit better once https://github.com/Enselic/cargo-public-api/issues/63 is fixed. There is currently an ongoing PR for that!

If needed, here is an example of per-word diffing and highlighting of trailing newline differences.

I see. I would try writing the same name as in your Cargo.toml. For example, if yours was toml [package] name = "caesor_cipher" I would try bin.name = "caesor_cipher" It seems that trycmd might ignore a test if the bin.name field is incorrect: https://github.com/assert-rs/trycmd/issues/105

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#meth...) but testing of example is still lacking. I've written trycmd to help (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/

- External documentation, see 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). 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/tutoria...). Its not great.

Another problem we found in clap was it was easy for our examples to build but harder to make sure they worked. This is why I wrote trycmd (example "tests").

Would love feedback on on some of the known questions or whatever else is on your mind!

The design is inspired by trybuild with thought given to how mdBook books could pull in content so you can verify a code sample, the command for running it, and the output. In considering how to keep clap's website up-to-date, I had this idea and threw it together to see how well it works. Overall, seems good with room for improvement. I'll have to give this a try on a real world program soon.