javadocs policies and rifles (was: javadoc vs. doxygen)

[Leo Simons <ma...@leosimons.com>]

On Fri, Jan 27, 2006 at 06:05:23AM -0500, Geir Magnusson Jr wrote:
> Zsejki Sorin Mikl�s wrote:
> >Geir Magnusson Jr wrote:
> >>Zsejki Sorin Mikl�s wrote:
> >>>Doesn't Harmony need Javadoc anyway just in order to be called "Java"?
> >>
> >>No.  IMO, we should *not* be creating a parallel set of javadoc for 
> >>J2SE.  There already is the standard set produced by the expert group 
> >>(part of the spec).
> >
> >I meant the tool.
> 
> Oh. <lowering rifle>  Sometimes I can't see past my own muzzle flash.

Heh. I pretty much agree with Geir that it doesn't make that much sense to
match Sun's javadocs in breadth or quality or function and I'm certainly not
interested in working on that myself.

But I don't think we need to discuss it a whole lot. I don't see a problem
if people do work on these bits. If someone feels that the javadocs from sun
are awkward or wrong or hard to comprehend (for example I've always felt the
javadoc for Object.equals() is painfully messed up, I can just imagine there
being dozens of java tutors out there who have written alternatives and who
have no place to go with that tidbit of info) and they want to work on
that within the harmony svn repo I can understand that. Signs are definitely
that with GPLv3 that work could be merged into eg classpath and we already
know it can be merged into sun's stuff upstream.

So I don't get why you're holding that rifle at all or why there was so much
discussion about this a while ago. Eg, the (non)existence of javadoc does not
strongly affect our ability to build a kick ass j2se implementation, so lets
just agree to accept sensible patches and not worry about a "javadoc policy"
too much :-)

Just two cents from the peanut gallery...

cheers!

LSD

Re: javadocs policies and rifles

[Leo Simons <ma...@leosimons.com>]

Various bits snipped...

On Fri, Jan 27, 2006 at 10:45:35AM -0500, Geir Magnusson Jr wrote:
>   If we are going to do javadoc for java*, and
>   we have to to be a serious implementation, I'd
>   like to ensure that there's no confusion with
>   the spec. 

+1 (as in, confusion == bad)

>   I'd like to simply put a link  to
>   the spec javadoc at the top of each class javadoc,
>   and then write anything we want after that.

+0 (as in, that's a technical detail I'm probably not going to help
    with, but I support the idea)

> Then it's very clear that the spec is 'there' (off in Sun-land), our 
> implementation notes, usage notes, comments, explanations, etc are here, 
> in Harmony Land.
> 
> And when we get permission to re-use spec javadoc in implementation, 
> which IMO is the Right Thing that Sun should do, then we just copy-paste 
> that in and keep going.

+1 (as in, "IMO", all java specs and their javadocs should be under some
    very liberal terms which are compatible with eg the apache license
    and the apache license policies)

> But Leo, there's a serious issue here.  I won't go into detail here to 
> avoid boring people unless asked.

No thanks, I think I pretty much get it now, where I didn't really get the
same message before.

Happy hacking!

LSD

Re: javadocs policies and rifles

[Geir Magnusson Jr <ge...@pobox.com>]

Leo Simons wrote:
> On Fri, Jan 27, 2006 at 06:05:23AM -0500, Geir Magnusson Jr wrote:
>> Zsejki Sorin Mikl�s wrote:
>>> Geir Magnusson Jr wrote:
>>>> Zsejki Sorin Mikl�s wrote:
>>>>> Doesn't Harmony need Javadoc anyway just in order to be called "Java"?
>>>> No.  IMO, we should *not* be creating a parallel set of javadoc for 
>>>> J2SE.  There already is the standard set produced by the expert group 
>>>> (part of the spec).
>>> I meant the tool.
>> Oh. <lowering rifle>  Sometimes I can't see past my own muzzle flash.
> 
> Heh. I pretty much agree with Geir that it doesn't make that much sense to
> match Sun's javadocs in breadth or quality or function and I'm certainly not
> interested in working on that myself.

It's important for other reasons as well.  Like it or not, that is the 
spec document.  We're not here to try and replace that.  We don't need 
the inevitable problems that would arise if we tried it.

> 
> But I don't think we need to discuss it a whole lot. I don't see a problem
> if people do work on these bits. If someone feels that the javadocs from sun
> are awkward or wrong or hard to comprehend (for example I've always felt the
> javadoc for Object.equals() is painfully messed up, I can just imagine there
> being dozens of java tutors out there who have written alternatives and who
> have no place to go with that tidbit of info) and they want to work on
> that within the harmony svn repo I can understand that. Signs are definitely
> that with GPLv3 that work could be merged into eg classpath and we already
> know it can be merged into sun's stuff upstream.

Sure - that's perfectly fine.  My position boils down to

   If we are going to do javadoc for java*, and
   we have to to be a serious implementation, I'd
   like to ensure that there's no confusion with
   the spec.  I'd like to simply put a link  to
   the spec javadoc at the top of each class javadoc,
   and then write anything we want after that.

Then it's very clear that the spec is 'there' (off in Sun-land), our 
implementation notes, usage notes, comments, explanations, etc are here, 
in Harmony Land.

And when we get permission to re-use spec javadoc in implementation, 
which IMO is the Right Thing that Sun should do, then we just copy-paste 
that in and keep going.

> 
> So I don't get why you're holding that rifle at all or why there was so much
> discussion about this a while ago.

It's a joke.   I was too busy on the "javadoc content" front when in 
fact the subject was really the javadoc tool.

We're all in agreement that this project is not about supplanting the 
spec, and I want to ensure we don't accidentally confuse people.  We've 
already faced similar issues before, and there's no upside, for anyone.

That said, I'm going to be thrilled when our implementation supplants 
Sun's as the defacto implementation. :)


  Eg, the (non)existence of javadoc does not
> strongly affect our ability to build a kick ass j2se implementation, so lets
> just agree to accept sensible patches and not worry about a "javadoc policy"
> too much :-)

Yep.

But Leo, there's a serious issue here.  I won't go into detail here to 
avoid boring people unless asked.

geir

> 
> Just two cents from the peanut gallery...
> 
> cheers!
> 
> LSD
> 
>