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 19:05:21 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.  If I did, 
I'm sorry the for the misunderstanding.

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 so it's clear

It's also nice when we want to note that that we're clarifying an 
uncertainty in the spec, for example...

> 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!)
>

Is there a way to tag Javadoc by language so that tools can generate 
javadoc trees per language?




> Regards,
> Tim
> 


Mime
View raw message