Tim Ellison wrote:
Loenko, Mikhail Y wrote:
Well, I'll try to summarize what we have
There are three types of methods:
1. Methods that are part of the API, they are specified, they follow the
Sun's spec and we have nothing to add.
2. Methods that are part of the API and we have something to add (ex.:
the spec allows multiple behaviors).
3. Private methods or methods in com.*, org.* areas etc.
I think we all agree that we have to document #3.
I agree it is good practice to document the implementation of some
non-API code for developers.
Some? why not all?
That documentation may or may not be
JavaDoc. For example, many people typically don't do a full JavaDoc
comment for a private method.
Where would you put it?
But it's not clear for
me what we do with #1 and #2. I suggest discussing #1 first.
We might want to omit documentation for #1 methods (though if the doc
describes all the methods except a single one - it might be confusing)
Yes, that would be confusing.
or put there some standard words (like this method is implemented
according to the spec) and either do or don't provide a link to the
Sun's spec.
In the .java source files we might either skip javadoc comment (though
it would not improve code readability) or provide some standard words
for all such methods.
Another option is to put reworded content of Sun's spec into the
documentation. I do not like this idea: if we say that our
implementation works according to our wording but not to the official
spec we might have problems with naming it Java (or we will have to say
"we implement our own spec that is semantically equivalent to Sun's
spec", which we'll have to prove first :).
There is only one way that you can call an implementation Java(tm) --
and that is to pass the JCK.
Moreover, we will need a
number of native English speakers who will volunteer to write the docs
for us.
I sense that there is an underlying reason for the objection to writing
JavaDoc ;-) Do you really *want* URLs to Sun's website, or do you think
that writing the doc will be too much effort, or ... ? How about
writing it in multiple languages if that's where our skills are?
AFAIK other projects that are implementing JSRs etc write the code and
documentation to go alongside it rather than link to the reference.
How do you go "alongside"?
Perhaps our friends involved with Classpath can give us an insight as to
whether they regret writing JavaDoc, or whether they see it as a
valuable part of the effort (assuming that they have written all the doc!).
Good idea.
So, what do we do with the methods that act exactly as specified?
My view is that we document them using our own words, and go for quality
documentation as well as quality implementation.
I agree that we should do that where it adds value, but I'm still a
believer in also including the link to the standard javadoc, represented
as such, because one has to believe that they were written by the
experts in the field, and that there is a coherent 'domain specific
jargon' used by those experts that one hopes is consistency throughout
some given API domain.
That said, we should be providing *augmentation* to that that's
important to our implementation.
geir
