I like your comment, but for the wrong reason: Explaining what a method DOES, goes against encapsulation principles. It creates coupling to implementation details, when what should be provided is just the interface. Any explanation can be exposed in business domain logic and documentation.
There are multiple pieces of documentation. Documenting what a method does is one of them, but primarily intended for maintainers of the system. Documenting its interface is meant for its users.
Both have great value, but at different times and to different people.
Indeed, was thinking the same thing while posting.
In practice though, I've mostly encountered lack of comprehensive developer docs, or they became outdated years ago. Most devs will point to source itself for documentation, unless for critical or certified software. If not the latter, the internal logic is usually scattered and not cohesive. So need to check dozens of files for each hypothesis about the original intentions and context.
