geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alan Cabrera <...@toolazydogs.com>
Subject RE: [PATCH] [JSR-88] JavaDoc
Date Thu, 21 Aug 2003 01:56:51 GMT
All good reasons.  I'm sold.  IDE is the most compelling to me.


Regards,
Alan

> -----Original Message-----
> From: Aaron Mulder [mailto:ammulder@alumni.princeton.edu] 
> Sent: Wednesday, August 20, 2003 10:25 PM
> To: 'geronimo-dev@incubator.apache.org'
> 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: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