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