geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alex Blewitt <Alex.Blew...@ioshq.com>
Subject Re: [PATCH] [JSR-88] JavaDoc
Date Fri, 22 Aug 2003 08:03:39 GMT
On Thursday, Aug 21, 2003, at 17:16 Europe/London, Aaron Mulder wrote:

> On Thu, 21 Aug 2003, Jason Dillon wrote:
>> Agreed.  It should suffice to put a link in the modules xdocs back to
>> the original api docs.
>
> What are your thoughts on the issues below?

Personally, I think that copying a bunch of JavaDoc is distinctly more 
effort than writing code. A bunch of methods may only take a few lines 
of code, but you have to write documentation for each as well as the 
class. And if you're going to do it properly (documented parameters, 
exception tags as well it can be quite an amount of work.

However, if someone's going to do it then I don't see any reason why 
the JD shouldn't be put in :-) I use an IDE that provides the links to 
embedded JavaDoc as well, and I agree that it would be a definitely 
useful feature to have.

The only problem is that there's a lot of stuff to be documented; in 
JavaMail, for example, the API is 100 classes and around 800 methods -- 
even assuming a conservative 3 lines per method and 5 lines per class, 
that's almost 3000 lines of text. It's going to take a long time to put 
anything in there.

I'd say go for it if you're willing to put the effort in for the 
JavaDoc, but it should be a low priority overall.

Alex.


Mime
View raw message