harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mikhail Loenko <mloe...@gmail.com>
Subject Re: writing full javadoc, or not
Date Wed, 01 Feb 2006 05:37:19 GMT
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.p.ellison@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.
>

Mime
View raw message