harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tim Ellison <t.p.elli...@gmail.com>
Subject writing full javadoc, or not (was: Re: javadoc vs. doxygen)
Date Tue, 31 Jan 2006 09:53:52 GMT
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 (t.p.ellison@gmail.com)
IBM Java technology centre, UK.

Mime
View raw message