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. Do you have an examples of *any* independent implementations of a JSR causing such confusion? 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), lots in XML) and not forgetting our close cousin, Classpath. 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'? >> 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. I suggest that we encourage developers to write full, quality javadoc comments; 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 -- Tim Ellison ([EMAIL PROTECTED]) IBM Java technology centre, UK.
