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 <[EMAIL PROTECTED]> 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 ([EMAIL PROTECTED]) > IBM Java technology centre, UK. >
