Yes! Particularly in languages with rich semantics and a tradition of meaningful identifiers, the primary focus on documentation where I've worked has been on 'why' rather than 'what.' In Ada, which separates specification/API from implementation, the comments in the spec explained what the package did (including errors/exceptions), and the comments in the body concentrated on capturing what was not obvious -to a maintainer- in the code. Ada culture strongly emphasized maintainability, and that was emphasized in code reviews.
On one project, I ended up as "the first maintainer", having to rewrite a package that was widely used throughout the large application. I had to live with that specification, although I did add comments on errors that could be signaled by the various operations. But I rewrote that package body twice, the first time for time performance, and the second time to minimize space (it was a generic package. The compiler was unable, due to the complexity, to do 'code sharing' automatically, so I ended up using a lot of compiler specific dirty tricks to manually implement shared generics. And I documented all the tricks and knowledge about what I was doing in that package body. I also delivered a 'warranty' with that, telling my successor afterI left that job, "If you get a bug report, contact me and I'll work with you to fix it." She never called, and about 10 years later we connected, and I asked: "Any bugs on that code?" "No, it worked perfectly.")
