Mailing-List: contact harmony-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: harmony-dev@incubator.apache.org
Received-SPF: neutral (asf.osuosl.org: 217.158.94.220 is neither permitted nor
 denied by domain of t.p.ellison@gmail.com)
Message-ID: <4402E621.6040307@gmail.com>
Date: Mon, 27 Feb 2006 11:44:33 +0000
From: Tim Ellison <t.p.ellison@gmail.com>
User-Agent: Thunderbird 1.5 (Windows/20051201)
MIME-Version: 1.0
To: harmony-dev@incubator.apache.org
Subject: [classlib] javadoc (the comments not the tool)  (was: Re: [jira]
 Resolved: (HARMONY-103) java.lang.StringBuilder Implementation for LUNI)
References: <003701c63834$69e09aa0$0d01a8c0@OFFICEDESKTOP>
 <440265D3.5010904@pobox.com>
In-Reply-To: <440265D3.5010904@pobox.com>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit

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.