> Similar to the "code should be self documenting - ergo: We don't write any comments, ever"

My counterpoint: Code can be self-documenting, reality isn't. You can have a perfectly clear method that does something nobody will ever understand unless you have plenty of documentation about why that specific thing needs to be done, and why it can't be simpler. Like having special-casing for DST in Arizona, which no other state seems to need:

https://en.wikipedia.org/wiki/Time_in_the_United_States

This isn't a counterpoint, it's just additional (and barely relevant) information.

Documenting it in a way that ensures it satisfies the example case would be preferred. You know, like with a test.