Absolutely agree.  Needs a bit of work to make that seamless -- either extracting from the classes, or linking to the javadoc, or maybe even some combo (ie javadoc extension).

So out of scope here but high on list of docs priorities I think.