For us, documentation lives in Markdown in Rustdoc comments above the things they document. There may be longer write-ups, examples, etc. at the module level.

For us, documentation lives in Markdown in Rustdoc comments above the things they document. There may be longer write-ups, examples, etc. at the module level. Documentation gets compiled into a docs.rs-style searchable website like so: https://docs.rs/tokio/1.36.0/tokio/ https://docs.rs/tokio/1.36.0/tokio/ Examples are compiled and run as part of the default CI toolchain. So when a piece of documentation refers to some code that was moved or renamed, it is a bug to not update references in Rustdoc comments. Comments can still get stale because some programmers write but don't read. But they're right there on your screen next to the code you're updating.