[jdom-interest] TODO subclassing [eg]

[Joseph Bowbeer]

Alex Rosen writes:

> Alternatives: (1) Rather than starting with "This implementation",
> 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.

Lacking any convention of our own, I was suggesting that we adapt the
convention that is used in (at least part of) the Java platform libraries.

I agree that "Info for subclassers" might be clearer.

Putting the comments in the javadoc as opposed to internal comments
reinforces the point that these classes are designed for inheritance and
therefore the implementation matters.

Subclassers should be able to count on the javadoc description of the
implementation remaining fairly constant from release to release.  They
shouldn't however be depending on undocumented properties of the
implementation.


----- original message -----
From: Alex Rosen arosen at silverstream.com
Date: Sun, 15 Apr 2001 20:48:25 -0400

> "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 implementation", 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