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