
Honestly, I think a big part of this isn't documentation practices so much as it is the expression problem. For a lot of the problems I tackle, the OO model is not appropriate for capturing program structure. Pairing this with Java's requirement of one class per file means that the actual functionality itself is spread out across a huge collection of classes and methods. The JavaDoc is just working with what it gets. This is one of the (many) reasons I prefer Haskell: the structure of Haskell programs matches the structure of the problems I need to solve (or at least, how I think about them).
I've also noticed this, and I agree with the above. I track down some random type and it's just a one method interface, so you can embed the "getter" in some random object. In another language, you would just pass a function. Track down another and it's an enumeration, to be passed to a factory, to generate subclasses of some abstract superclass. In another language it would just be an ADT (the enumeration means the java can't add new subtypes anyway) and a function to operate on it in probably 1+n lines, but in java we're looking at 1+1+n+1 files, each with their overhead and directories, and of course their own names, so you have to track down each one, and remember what each name means as you try to understand the actual logic. In the specific example above, it was just reinventing Data.Monoid, so in haskell you wouldn't have to remember any new names, provided you already know 'mempty' and 'mappend'. Also the java style OO insistence that functions go with the data rather than with their related functions can require you to scatter the implementation of one logical function far and wide... ostensibly a feature I suppose, but can also be a liability. Et cetera. Sometimes I think it's just me, that I don't think in an OO way, but then again, the examples above were written by someone else who has done OO all his life. For me it really is the explosion of names that leads to overload. When writing haskell, I hardly ever finding myself wanting or reinventing subtyping, so for me at least, the haskell half of the expression problem is the practical half.