[simonw]

I went through a phase a few years ago of writing ESSAYS in my commit messages, on the basis that they were the only form of documentation which I trusted to stay 100% synchronized with the code.

Eventually I realized that there's a better way to do this: keep your documentation in the same repo as your code, and construct commits that update the documentation AND the tests AND the code all in the same unit. Now your commit message can be much shorter, but you still guarantee that the documentation is exactly aligned with the code that it talks about.

It also means you can add unit tests that check that code is covered by your documentation! https://simonwillison.net/2018/Jul/28/documentation-unit-tes...

[lytedev]

Just to bring up a neat point, this doesn't guarantee that the documentation and the code are the same, as you could change code without updating documentation.

A very slick way of enforcing this that I've seen is having actual unit tests in your documentation (and of course a CI tool to enforce that tests pass). This is something that I think is extremely cool about Elixir! It forces you to think about testing, documentation (with ACTUAL examples!!), and the problem you're solving all at once. It's a very neat concept.

https://elixir-lang.org/getting-started/mix-otp/docs-tests-a...

[sambal]

Python and Rust go the “documentation test” route as well.

Go goes the opposite direction with “testable examples” that are written alongside test code and added to generated documentation.

https://docs.python.org/2/library/doctest.html

https://doc.rust-lang.org/rustdoc/documentation-tests.html

https://golang.org/pkg/testing/#hdr-Examples

[j88439h84]

AFAIK Doctest actually comes from Python originally.

[j88439h84]

Why put the class docs in a separate .rst instead of just leaving it in the class docstring? I suppose there's syntax highlighting, though that seems like an editor issue.