Recently, I ripped usage examples out of a rust project's README.md, and put them in doc comments. Almost all of them were broken due to small changes over time, and I never remembered to update the readme. `cargo test` runs doc comments like mini integration tests, so now the examples never rot. I wish more languages and tools had this feature.
It means having to go to the linked docs (which are automatically pushed to the repo's github pages) to see examples, but I think this is a reasonable tradeoff.
