geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Aaron Mulder <ammul...@alumni.princeton.edu>
Subject RE: [PATCH] [JSR-88] JavaDoc
Date Thu, 21 Aug 2003 02:25:12 GMT
On Wed, 20 Aug 2003, Cabrera, Alan wrote:
> Is it a good idea to put JavaDocs in our API code?  For mx4j, the JMX specs
> group suggested that we don't put comments into our clean-room API code so,
> we didn't.  The idea being that there should be a single source for the spec
> and JavaDocs, this being www.jcp.org.  I see their point but do not feel
> strongly about it.

	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 JCP.org.  
Second, JCP.org 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).

	So, bottom line, I didn't write it for giggles, I wrote it because 
we were having trouble without it.  Not something we couldn't work around, 
but why put extra hurdles in the path?

Aaron

> > -----Original Message-----
> > From: Aaron Mulder [mailto:ammulder@alumni.princeton.edu] 
> > Sent: Wednesday, August 20, 2003 6:37 PM
> > To: geronimo-dev@incubator.apache.org
> > Subject: [PATCH] [JSR-88] JavaDoc
> > 
> > 
> > 	I've started adding the JavaDoc to the JSR-88 spec 
> > tree.  Here are the first couple packages; the ones we're 
> > currently implementing.  It's based on the Sun JavaDoc, but 
> > with lots of typos fixed and a couple clarifications.
> > 
> > Aaron
> > 
> > (Hopefully this URL will work!)
> > 
> http://jira.codehaus.org/secure/ViewIssue.jspa?key=GERONIMO-3
> 
> 
> ---------------------------------------------------------------- 
>       Visit our Internet site at http://www.reuters.com 
> 
> Get closer to the financial markets with Reuters Messaging - for more
> information and to register, visit <http://www.reuters.com/messaging> 
> 
> Any views expressed in this message are those of  the  individual sender,
> except  where  the sender specifically states them to be the views of The
> Reuters Group.
> 



Mime
View raw message