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!

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.

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

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.

"Does it? You can just alter the code and forget to alter the documentation above the functions/methods"

Yes you can forget, but the barrier is much, much, much lower than having to modify a document god knows where.

For abstract descriptions of what the code does, sure. But for small things like documenting the purpose of arguments, an IDE should warn about changes that are not reflected in the doc comment (type or a new arg altogether). IntelliJ IDEs are pretty good at that.

Rust for example also warns about code included in the doc comments example section which is invalid.

I've used swagger with java and golang and both of them generate docs directly from the code, no comments needed.

But what's the point then? If there's a tool, that can make "documentation" out of source code, I can just look at the source code?

Mostly it collates all your endpoints more easily, generates clients for different languages, genearates an online documentation and test page that makes your service self describing, and can be published out to third parties that dont have access to your code.

The tool parses out the bits that you're interested in. If you want to know what year the proverbial apple fell on Isaac Newton's head, you can get a biography and start reading, or you can Google and let the machine filter out the irrelevant bits.

If I'm looking at documentation, I want the inputs and outputs and a brief description of what it does. I care very little about the implementation, or I would write my own.

Presumption that all code is open source. The war is won :-)