4 ms·
>third party libraries (even extremely popular ones) have outdated example code or docs that are inconsistent with actually released versions. That's actually
by joshmarlow 6y ago
>third party libraries (even extremely popular ones) have outdated example code or docs that are inconsistent with actually released versions.
That's actually one of my big pet-peeves about OSS. This is especially annoying because the Rust ecosystem already has a really nice solution to the problem - skeptic ([0]).
Skeptic finds Rust snippets in markdown files and dynamically builds tests to run them. So if your docs go out of sync with your code, `cargo test` fails.
[0] - https://github.com/brson/rust-skeptic https://github.com/brson/rust-skeptic
- giancarlostoro 6y agoKinda sad it looks like that was last updated 2 years ago
- masklinn 6y agoskeptic should only be useful for arbitrary markdown files though, `cargo test` should run the docstring snippets. The example snippets are more difficult to craft though, as they need to be "self-contained" and you need to hide the bits you don't want to show by marking them as a pseudo-comment using `#`. Rustdoc also has a `--test` flag. Tested it on clap (no specific reason, just have a checkout locally) and it ran 314 snippets from the docs so seems to work.
- giancarlostoro 6y agoMy main concern is if Rust changes significantly in a few years and this utility breaks then.
- joshmarlow 6y agoThat's a reasonable concern. IMO, a tool like Skeptic would add a lot of value to the ecosystem if deployed widely. It would be really cool if something equivalent was integrated into cargo.