All good reasons. I'm sold. IDE is the most compelling to me.
Regards, Alan > -----Original Message----- > From: Aaron Mulder [mailto:[EMAIL PROTECTED] > Sent: Wednesday, August 20, 2003 10:25 PM > To: '[EMAIL PROTECTED]' > Subject: RE: [PATCH] [JSR-88] JavaDoc > > > 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:[EMAIL PROTECTED] > > > Sent: Wednesday, August 20, 2003 6:37 PM > > > To: [EMAIL PROTECTED] > > > 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. > > > >
