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 Re: writing full javadoc, or not
Date Tue, 31 Jan 2006 20:56:50 GMT
Geir Magnusson Jr wrote:
> Tim Ellison wrote:
<snip>
>> 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.

I'm fine with that.

<snip>
>> 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.

Cool, then I apologize for misunderstanding your proposal.

>> I suggest that we encourage developers to write full, quality javadoc
>> comments; 
> 
> Kittens are cute!

Humpf. I'm allergic to cats.

> 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...

Agreed -- we should be able to maintain such links as a doclet, since
their path from some given root is well-defined.  Any volunteers to
write this?

>> 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?

Not that I'm aware of, but it would be very cool.

Regards,
Tim

-- 

Tim Ellison (t.p.ellison@gmail.com)
IBM Java technology centre, UK.

Mime
View raw message