This comment illustrates exactly the problem with the bulk of the documentation. Our tendency is to document classes, not usage patterns. This makes the documentation useful for people who already know what they're doing, but not so helpful for people who don't.
I'd also try to make class documentation as brief as possible and move the longer explanations to specific tutorials. Also people who do know how things work have to quickly look up methods at time. Long helpfiles make that difficult.
-- .