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.
