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.
