[jdom-interest] TODO subclassing [eg]

[Rosen, Alex]

> "The class must document precisely the effects of overriding any method.
> [...]  In other words, the class must document its self-use of overridable
> methods: for each public or protected method, the documentation must
> indicate which overridable methods are invoked by that method, in what
> sequence they are invoked, and how the results of each invocation affect
> subsequent processing. By convention, this description is placed at the end
> of the javadoc comment for each method, and begins with the
> phrase _This implementation_."
>
> The java.util.AbstractCollection javadoc is good a example.

Hmm... I'm not sure I like the general philosophy of mixing in the
documentation for users with the documentation for subclassers. It's not too
bad in the AbstractCollection case, because the implementation is simple. But
for a more complicated class, you'd make the JavaDoc a lot bigger for everyone,
even though only subclassers (the uncommon case) would benefit. Ideally, you'd
have two sets of JavaDoc - one for users, and one for subclassers.
Alternatives: (1) Rather than starting with "This implmementation", start with
"Info for subclassers:" or something, to make it clearer. (2) Put the info for
subclassers in non-JavaDoc comments in the code. After all, this is an open
source project, and the odds are that subclassers will be looking at the
source.

Alex Rosen
SilverStream Software