[bsder]

Then that's poor documentation.

Documentation, like comments, is most useful when it answers "why" sometimes "how" but rarely "what". And "why" changes much more slowly.

It's why I find API documentation to border on useless. I need examples and rationale, not variable names.