Re: writing full javadoc, or not

[Mikhail Loenko <ml...@gmail.com>]

It is not clear yet who is going to read that Harmony javadoc?

If it is IDE users only then maybe it is better to write a plug-in that
would show hints from official spec site for java.* methods?

Thanks,
Mikhail

On 2/1/06, Tim Ellison <t....@gmail.com> wrote:
> Geir Magnusson Jr wrote:
> > Tim Ellison wrote:
> <snip>
> >> Would it help to avoid your confusion if there was a disclaimer in the
> >> generated HTML along the lines that 'this is not a JSE spec'?
> >
> > Sure - and I think that a link to the spec would help too.
>
> I'm fine with that.
>
> <snip>
> >> You know what Sunny means ...  there is a significant difference to
> >> usefulness in an IDE whether your JavaDoc has a full description of the
> >> behaviour with parameter descriptions, throws, returns etc. compared to
> >> a simple URL.
> >
> > Great.  Put all of that.  But also put the URL to the Spec javadoc.  We
> > can write endless pages of whatever we want, and can run quality circles
> > around the spec javadoc.  (Most would argue that isn't very hard)  And
> > as long as we say "We aren't the spec.  The spec is <a
> > href=....>here</a>"  then I think we're cool.  We are then taking good
> > care of our users, as well as being "good citizens" and avoiding any
> > confusion regarding what the spec is.
>
> Cool, then I apologize for misunderstanding your proposal.
>
> >> I suggest that we encourage developers to write full, quality javadoc
> >> comments;
> >
> > Kittens are cute!
>
> Humpf. I'm allergic to cats.
>
> > I don't think anyone was suggesting anything other than that.  If I did,
> > I'm sorry the for the misunderstanding.
> >
> > What I am suggesting is that no matter what else we do, if it's a spec
> > class or interface, we point to the spec javadoc as well so it's clear
> >
> > It's also nice when we want to note that that we're clarifying an
> > uncertainty in the spec, for example...
>
> Agreed -- we should be able to maintain such links as a doclet, since
> their path from some given root is well-defined.  Any volunteers to
> write this?
>
> >> if people are not comfortable writing descriptive comments in
> >> English then I suggest we accept the code and leave it as a task for
> >> others to complete the doc (and if there is a way to capture the comment
> >> in their preferred language that would be even better!)
> >
> > Is there a way to tag Javadoc by language so that tools can generate
> > javadoc trees per language?
>
> Not that I'm aware of, but it would be very cool.
>
> Regards,
> Tim
>
> --
>
> Tim Ellison (t.p.ellison@gmail.com)
> IBM Java technology centre, UK.
>

Re: writing full javadoc, or not

[Vladimir Gorr <vv...@gmail.com>]

I agree with Mikhail it doesn't sense to write own documentation for
Harmony.
If we implement the J2SE in according to 1.5 specifications it'd be not bad
to link
to the official documentation to avoid any errors and misunderstandings. For
this purpose
new doclet can be implemented as it was done for the security contribution
and it should be processed by javadoc.

Thanks,
Vladimir Gorr
Intel Middleware Products Division.


On 2/1/06, Mikhail Loenko <ml...@gmail.com> wrote:
>
> It is not clear yet who is going to read that Harmony javadoc?
>
> If it is IDE users only then maybe it is better to write a plug-in that
> would show hints from official spec site for java.* methods?
>
> Thanks,
> Mikhail
>
> On 2/1/06, Tim Ellison <t....@gmail.com> wrote:
> > Geir Magnusson Jr wrote:
> > > Tim Ellison wrote:
> > <snip>
> > >> Would it help to avoid your confusion if there was a disclaimer in
> the
> > >> generated HTML along the lines that 'this is not a JSE spec'?
> > >
> > > Sure - and I think that a link to the spec would help too.
> >
> > I'm fine with that.
> >
> > <snip>
> > >> You know what Sunny means ...  there is a significant difference to
> > >> usefulness in an IDE whether your JavaDoc has a full description of
> the
> > >> behaviour with parameter descriptions, throws, returns etc. compared
> to
> > >> a simple URL.
> > >
> > > Great.  Put all of that.  But also put the URL to the Spec
> javadoc.  We
> > > can write endless pages of whatever we want, and can run quality
> circles
> > > around the spec javadoc.  (Most would argue that isn't very hard)  And
> > > as long as we say "We aren't the spec.  The spec is <a
> > > href=....>here</a>"  then I think we're cool.  We are then taking good
> > > care of our users, as well as being "good citizens" and avoiding any
> > > confusion regarding what the spec is.
> >
> > Cool, then I apologize for misunderstanding your proposal.
> >
> > >> I suggest that we encourage developers to write full, quality javadoc
> > >> comments;
> > >
> > > Kittens are cute!
> >
> > Humpf. I'm allergic to cats.
> >
> > > I don't think anyone was suggesting anything other than that.  If I
> did,
> > > I'm sorry the for the misunderstanding.
> > >
> > > What I am suggesting is that no matter what else we do, if it's a spec
> > > class or interface, we point to the spec javadoc as well so it's clear
> > >
> > > It's also nice when we want to note that that we're clarifying an
> > > uncertainty in the spec, for example...
> >
> > Agreed -- we should be able to maintain such links as a doclet, since
> > their path from some given root is well-defined.  Any volunteers to
> > write this?
> >
> > >> if people are not comfortable writing descriptive comments in
> > >> English then I suggest we accept the code and leave it as a task for
> > >> others to complete the doc (and if there is a way to capture the
> comment
> > >> in their preferred language that would be even better!)
> > >
> > > Is there a way to tag Javadoc by language so that tools can generate
> > > javadoc trees per language?
> >
> > Not that I'm aware of, but it would be very cool.
> >
> > Regards,
> > Tim
> >
> > --
> >
> > Tim Ellison (t.p.ellison@gmail.com)
> > IBM Java technology centre, UK.
> >
>