harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Geir Magnusson Jr <g...@pobox.com>
Subject Re: javadocs policies and rifles
Date Fri, 27 Jan 2006 15:45:35 GMT

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 :-)


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


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

View raw message