4 ms·
One of my personal pet peeves is when library examples don't actually work anymore due to API changes (or typos). There's actually a really great solution in t
by joshmarlow 7y ago
One of my personal pet peeves is when library examples don't actually work anymore due to API changes (or typos).
There's actually a really great solution in the Rust ecosystem that I would love to see used more widely - Skeptic [0]. It's a tool that parses markdown, finds Rust and builds it as an auto-generated test. If the example is no longer valid, it breaks your build.
[0] - https://github.com/budziq/rust-skeptic https://github.com/budziq/rust-skeptic
- steveklabnik 7y agoSo, to be clear, skeptic helps with extra markdown files you've written. Rustdoc will already do this with every example you write in your API documentation. It's very good though! (mdbook has a similar feature)
- joshmarlow 7y agoGood point - thanks for calling it out!
- asdkhadsj 7y agoAnother approach which I've liked in the past to solve this issue is to generate your README's from Rust Source. This has the same net output but the readme lives within Rustdoc. I think I prefer it living in Rustdoc because then your README is also on docs.rs and whatnot. But, I can see some downsides with that too. Not every README should be identical to the API docs. Not sure where the balance should sit.