RE: [RESULT] ( Was Re: [VOTE] Accept JIRA contribution HARMONY-16 (Intel's contrib of security code for classlib))

["Loenko, Mikhail Y" <mi...@intel.com>]

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
2. Reword the spec. More likely to be legal
3. Replace the tag with a different one and provide taglet to build the
doc from the Harmony sources and Sun's spec.

Currently IBM's contribution seems to have #2. Does anyone have an
opinion?

Thanks,
Mikhail Loenko
Intel Middleware Products Division

>-----Original Message-----
>From: Geir Magnusson Jr [mailto:geir@pobox.com]
>Sent: Friday, December 30, 2005 10:48 PM
>To: harmony-dev@incubator.apache.org
>Subject: Re: [RESULT] ( Was Re: [VOTE] Accept JIRA contribution
HARMONY-16 (Intel's contrib of
>security code for classlib))
>
>
>
>Tim Ellison wrote:
>> Geir Magnusson Jr. wrote:
>> <snip>
>>
>>>I'll finish moving to SVN and we'll put into the classlib tree, I
suppose.
>>
>>
>> Great.  Thanks again Mikhail and the team!
>>
>> I suggest you either put it into the classlib tree at
>> "classlib/java-src/security2" or leave it in the sandbox, then we can
>> merge it into the existing security structure without breaking the
world.
>
>I'll go for the former and try to whip it into common shape, and we can
>then decide how we do this - drop the existing security if security2 is
>a superset, or merge.
>
>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.
>
>Also will give me a good change to frame out the test infra.
>
>
>>
>> Regards,
>> Tim
>>

Writing JavaDoc (was: Re: [RESULT] ( Was Re: [VOTE] Accept JIRA contribution HARMONY-16 (Intel's contrib of security code for classlib)))

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

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.

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.

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

Regards,
Tim

> Currently IBM's contribution seems to have #2. Does anyone have an
> opinion?
> 
> Thanks,
> Mikhail Loenko
> Intel Middleware Products Division
> 
> 
>>-----Original Message-----
>>From: Geir Magnusson Jr [mailto:geir@pobox.com]
>>Sent: Friday, December 30, 2005 10:48 PM
>>To: harmony-dev@incubator.apache.org
>>Subject: Re: [RESULT] ( Was Re: [VOTE] Accept JIRA contribution
> 
> HARMONY-16 (Intel's contrib of
> 
>>security code for classlib))
>>
>>
>>
>>Tim Ellison wrote:
>>
>>>Geir Magnusson Jr. wrote:
>>><snip>
>>>
>>>>I'll finish moving to SVN and we'll put into the classlib tree, I
> 
> suppose.
> 
>>>
>>>Great.  Thanks again Mikhail and the team!
>>>
>>>I suggest you either put it into the classlib tree at
>>>"classlib/java-src/security2" or leave it in the sandbox, then we can
>>>merge it into the existing security structure without breaking the
> 
> world.
> 
>>I'll go for the former and try to whip it into common shape, and we can
>>then decide how we do this - drop the existing security if security2 is
>>a superset, or merge.
>>
>>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.
>>
>>Also will give me a good change to frame out the test infra.
>>
>>
>>
>>>Regards,
>>>Tim
>>>
> 
> 

-- 

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