harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Geir Magnusson Jr <g...@pobox.com>
Subject Re: writing full javadoc, or not
Date Tue, 31 Jan 2006 17:13:42 GMT

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

View raw message