Four kinds of documentation

Re:Four kinds of documentation by steveklabnik on Friday October 18, 2019 @10:35AM (#21291718)

With Rust, we help mitigate this by running code examples in API documentation as tests. That doesn't stop people from opting out, and it doesn't solve every problem, but it's still quite useful!

[ Parent | on HN ]

Re:Four kinds of documentation by mdtusz on Friday October 18, 2019 @11:07AM (#21291997)

I'm sure you know because you're Steve Klabnik, but for other readers: you can enforce documentation for public items in a crate by adding `#![deny(missing_docs)]` to the `lib.rs` file.

Then it just takes some self-control and gold code reviews to make sure you're writing good documentation rather than just short stubs to silence the error.

[ Parent | on HN ]

Re:Four kinds of documentation by steveklabnik on Friday October 18, 2019 @11:23AM (#21292132)

You’d think, but I have certainly committed (in both the colloquial and git sense) a dummy /// TODO comment to silence this warning... oops

[ Parent | on HN ]

Re:Four kinds of documentation by joshmarlow on Friday October 18, 2019 @04:56PM (#21295012)

I'm going to hijack this thread to recommend Rust Skeptic - https://github.com/budziq/rust-skeptic

It checks for rust snippets in markdown files and attempts to build them when you run `cargo test`. It helps keep docs and code in sync.

[ Parent | on HN ]