[classlib] javadoc (the comments not the tool) (was: Re: [jira] Resolved: (HARMONY-103) java.lang.StringBuilder Implementation for LUNI)

[Tim Ellison <t....@gmail.com>]

Geir Magnusson Jr wrote:
> 
> 
> Nathan Beyer wrote:
>> 1. Javadoc - Yeah, I didn't know what was the right thing to do in
>> regards
>> to the javadoc. It wasn't 100% copy and paste, but the class-level and
>> some
>> of the methods were pulled. My thought was that if we're considering the
>> Javadoc as the specification for the interface, then it was fair game. I
>> know this was discussed a bit earlier on the list, but I don't recall any
>> real resolution. I'll checkout the code an insert original comments.
>> Let me
>> know if there are any guidelines I should follow.
> 
> Here's the rule - don't copy Sun's spec material as it's copyrighted
> work and while using it in this way is arguably fair use, Sun has
> specifically said no to this, and it's not worth the fight.
> 
> Here's the guidlines I'd like to see :
> 
> 1) if it's org.apache.harmony, do whatever you want

Yep.  Though if the type/method is not internal you should do a
reasonable job so other module developers can use your code.

> 2) if it's java[x].* and you want to do javadoc, please put a pointer to
> the relevant Sun spec, and then go to town...

I'd say just go to town and  write a good javadoc comment -- we can add
in the link to Sun's spec document automagically at javadoc creation
time since the mapping between the two is well understood.

Regards,
Tim

> geir
> 
> (next time, can you try to interleave your response with what you are
> responding to if it's multi subject?  Helps those of us that are
> catching up...)
> 

-- 

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