I wrote:
	> It isn't *JAVA* that needs the sources if you want to extend it,
	> it's the *PROGRAMMER* who needs the sources.  There can be important
	> information about a class, such as a class invariant, stated as plain
	> comments, not Javadoc comments.

Dustin Sallings <dustin at spy.net> retorted:
	Your point only seems valid if an API has misleading documentation and  
	was not written to be reused.
	
This is so far from the truth that there isn't much point in responding
to anything else in the message.  It's a really elementary point, which
has been thoroughly understood for a while.  A class has TWO kinds of
clients, which we might call "HAS-A" clients (which use the class) and
"IS-A" clients (which extend it).

Typical JavaDoc documentation (certainly the documentation for the
Java Collection classes) is documentation for HAS-A clients.  It is
what it is precisely because these classes *are* written to be re-used.
There isn't the slightest suggestion that any of it is misleading.
It just isn't aimed at IS-A clients.  By far the commonest form of
re-use is from HAS-A clients, not IS-A clients, so it makes good engineering
sense to aim the documentation at the majority of reusers.

HAS-A documentation may, however, be *incomplete* for IS-A reuse.
"Incomplete" is a very different thing from "misleading".

Obviously documentation _could_ be written to be fully adequate for
people writing both kinds of client.  But it usually isn't.  And it's
not at all clear that this is a bad thing.  It's at least arguable that
suppressing detail principally useful to IS-A clients makes the
documentation *more* useful for HAS-A clients.