geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Aaron Mulder <>
Subject Re: [PATCH] [JSR-88] JavaDoc
Date Thu, 21 Aug 2003 16:16:20 GMT
On Thu, 21 Aug 2003, Jason Dillon wrote:
> Agreed.  It should suffice to put a link in the modules xdocs back to 
> the original api docs.

	What are your thoughts on the issues below?


On Wed, 20 Aug 2003, Aaron Mulder wrote:
>       Well, I have to disagree with the JMX group.  First of all, my IDE
> is pretty good about working with source files and JavaDoc, and when
> it's not clear what something does or how it should be used or
> implemented, I like to jump to either the code or the JavaDoc.  It's
> pretty useless when the code is undocumented, and I have no such hot
> links to Second, is bad because most of the specs go
> through several JSRs in their lifetime (JSR-88 will live on under J2EE
> 1.4, which is a very near-term change, and I'm sure the JSR for J2EE 1.5
> won't be all that far away).  Third, if we're distributing code, we
> should probably be distributing documentation for it, and I don't see
> why the APIs should be different.  Fourth, the standard API
> documentation for JSR-88 is riddled with errors (Q: What class does it
> mean when it says ConfigBean [there is no such class]?  A: Not
> DConfigBean, in fact it means DDBean, and where it says "server
> configuration", it means "standard J2EE application configuration").  
> While I've been in communication with Rebecca (the spec lead) and she
> may be able to squeeze some fixes into the v1.1 API doc, it's not
> available now.  Fifth, speaking of which, we need to implement v1.1 for
> J2EE 1.4, and currently there is no API doc available for it -- you have
> to refer to v1.0 and then check the v1.1 changelog, which scatters API
> source code changes throughout numerous sections of descriptive text and
> examples, and then if you want JavaDoc you have to generate it yourself.
>       As a case in point, the code I've been working with Chris on had
> two significant problems -- it omitted all the v1.1 items since they're
> in neither the Sun class files nor the Sun JavaDoc, and we both agreed
> together on an incorrect return value for one of the methods because we
> overlooked the definition in the JavaDoc (for my part, because I went to
> look for it in our source code and it wasn't there).

View raw message