geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jason Dillon <ja...@coredevelopers.net>
Subject Re: [PATCH] [JSR-88] JavaDoc
Date Fri, 22 Aug 2003 08:06:04 GMT
> 	What are your thoughts on the issues below?

Um... basically I do not care too much ;-)  My only concern is that 
docs be kept updated.

--jason


> Aaron
>
> 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 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).
>
>


Mime
View raw message