harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Magnusson, Geir" <geir.magnus...@intel.com>
Subject RE: Writing JavaDoc (was: Re: [RESULT] ( Was Re: [VOTE] Accept JIRA contribution HARMONY-16 (Intel's contrib of security code for classlib)))
Date Tue, 10 Jan 2006 15:49:40 GMT

> -----Original Message-----
> From: Tim Ellison [mailto:t.p.ellison@gmail.com] 
> Sent: Tuesday, January 10, 2006 5:26 AM
> To: harmony-dev@incubator.apache.org
> Subject: Writing JavaDoc (was: Re: [RESULT] ( Was Re: [VOTE] 
> Accept JIRA contribution HARMONY-16 (Intel's contrib of 
> security code for classlib)))
> Loenko, Mikhail Y wrote:
> > Thanks for accepting the contribution
> > 
> > 
> >>There's a bit of things that come out of this, like the
> >>"com.intel.drl.spec_ref" javadoc tag that we should 
> convert, and such.
> > 
> > 
> > What would be the best for those javadocs? We can have 3 possible
> > options:
> > 1. Copy-paste from the spec. Not sure it is legal
> This one definitely has to be out.  The Sun JavaDoc is a
> copyrighted/licensed work so making a verbatim copy is unacceptable.
> > 2. Reword the spec. More likely to be legal
> As I see it, the JavaDoc fulfils (at least) two purposes.  It embodies
> the java spec (i.e. the definition of the standard library's 
> behaviour),
> and it is the principal developer documentation (i.e. how to use the
> library).  We do not want to change the specification in any way, but
> can enhance the usability of the documentation to developers.
> For example, it would IMHO be wrong to specify the behaviour 
> of a method
> with more/less restrictions than the original reference 
> javadoc, because
> that implies that developers can make assumptions on one 
> implementation
> that they cannot on the other.  However, it is reasonable to give more
> examples, usecases, even performance, threading guidelines, 
> etc. that do
> not change the functional specification.

Yes - augmenting the spec with information about our implementation.

> So I'd say writing some JavaDoc, that was neither a direct copy of the
> original, nor 'enhancing' the specification, can provide value to
> developers.

But I think that we need to be clear, pointing to the Sun javadoc as the
specificatoin for J2SE, like it or not.  If not, we ensure that we work
on the next rev of J2SE to fix the javadoc.

However, we should certainly augment.

> > 3. Replace the tag with a different one and provide taglet 
> to build the
> > doc from the Harmony sources and Sun's spec.
> If I understand this correctly, then I don't see how this is
> substantially different to option (1)?  Whether it is a human 
> that does
> the cut-n-paste into the Harmony release, or a doclet, the result
> includes somebody else's work.

Right - we don't copy Sun's JavaDoc content.

For  java.*, I think that we can have a a "implementation notes javadoc"
if we need to, and of course javadoc our implementation well?


Geir Magnusson Jr
+1 203 665 6437  

View raw message