Tim Ellison wrote:
Geir Magnusson Jr wrote:
Like it or not, Sun's javadoc is the spec. We can get involved in the
EG and help fix the javadoc of course, and we can add additional
commentary about the our interpretation and implementation to
improve it, but we need to ensure that we take reasonable steps to
avoid confusion.
I agree with all that -- the spec for our project, of course, being in
javadoc and the JLS and VM-spec and JCK and ultimately 'the way the
reference implementation works', as anyone who has had to implement from
JavaDoc alone knows only too well.
However, I don't understand your paranoia about a hypothetical
third-party's misconception that Harmony is redefining the JSE
specification.
You can call it paranoia if you want, but we've already experienced
people thinking that we are trying to fork and re-define Java.
Do you have an examples of *any* independent implementations of a JSR
causing such confusion?
We are pretty special right now. Doing J2SE is a Big Deal. It
shouldn't be - this is an environment where independent implementations
are the way things are done. However, we're special because of the
particular spec we're doing.
There are plenty of examples to the contrary,
including many projects hosted here at Apache (I can't believe they are
all RI's such as JetSpeed (JSR168), Jackrabbit(JSR170),
For example, Jackrabbit has a pointer to the javadoc at Day software,
who is the speclead...
lots in XML) and
not forgetting our close cousin, Classpath.
I was thinking about this. Others include Geronimo, which doesn't
reproduce the J2EE spec, JDO, which is place where the EG is working for
JDO2 so that might have the javadoc, tomcat which isn't the RI but was
the source for it, so there is javadoc there in the servletAPI
subproject. Very baffling, actually.
Would it help to avoid your confusion if there was a disclaimer in the
generated HTML along the lines that 'this is not a JSE spec'?
Sure - and I think that a link to the spec would help too.
and a related comment that Sunny made about IDEs that grok JavaDoc
comments to help users & developers
The argument isn't about not having javadoc - we have to have javadoc,
for both java* and org.apache.harmony*.
You know what Sunny means ... there is a significant difference to
usefulness in an IDE whether your JavaDoc has a full description of the
behaviour with parameter descriptions, throws, returns etc. compared to
a simple URL.
Great. Put all of that. But also put the URL to the Spec javadoc. We
can write endless pages of whatever we want, and can run quality circles
around the spec javadoc. (Most would argue that isn't very hard) And
as long as we say "We aren't the spec. The spec is <a
href=....>here</a>" then I think we're cool. We are then taking good
care of our users, as well as being "good citizens" and avoiding any
confusion regarding what the spec is.
I suggest that we encourage developers to write full, quality javadoc
comments;
Kittens are cute!
I don't think anyone was suggesting anything other than that.
What I am suggesting is that no matter what else we do, if it's a spec
class or interface, we point to the spec javadoc as well.
if people are not comfortable writing descriptive comments in
English then I suggest we accept the code and leave it as a task for
others to complete the doc (and if there is a way to capture the comment
in their preferred language that would be even better!)
Regards,
Tim
