On Sunday, Sep 14, 2003, at 17:15 US/Pacific, Richard A. O'Keefe wrote:

> 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.
> 	
> 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.

	When you build javadoc, you have the option of including protected 
methods (only useful for IS-A) or just public (useful for HAS-A).  The 
javadocs from sun include the protected methods, which suggests to me 
that they're there for IS-A.

	My current job requires me to understand this stuff really well and 
I've seen it work.  I believe the assertion you're making is that the 
only good documentation is source code.  Perhaps it's the most true, 
but I believe that any failing for either form of reuse is either a 
design problem or a documentation problem.

> 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.

	It certainly can...but it really depends on how the documentation is 
organized.

	java.util.ArrayList is a subclass of java.util.AbstractList (which is, 
itself, a subclass of java.util.AbstractCollection).  The latter two 
classes are *only* useful for IS-A relationships, and their 
documentation describes what you need to do produce your own 
implementations.  From that, you can infer what ArrayList had to do to 
complete it...or you can just use AbstractList...from the documentation:

	 To implement an unmodifiable list, the programmer needs only to 
extend this class and 	provide implementations for the get(int index) 
and size() methods.

	To implement a modifiable list, the programmer must additionally 
override the set(int 	index, Object element) method (which otherwise 
throws an 	UnsupportedOperationException. If the list is variable-size 
the programmer must 	additionally override the add(int index, Object 
element) and remove(int index) 	methods.

	Seems pretty clear what you've got to do, and doesn't require access 
to the source.

--
SPY                      My girlfriend asked me which one I like better.
pub  1024/3CAE01D5 1994/11/03 Dustin Sallings <dustin at spy.net>
|    Key fingerprint =  87 02 57 08 02 D0 DA D6  C8 0F 3E 65 51 98 D8 BE
L_______________________ I hope the answer won't upset her. ____________