Michael Jakl wrote:
Hi!
The documentation I found in Vysper proved very helpful and - of course - more
of it would do good. Anyway I'd second the view that good documentation
shouldn't repeat what the code says best. The HTML argument is a good one, but
IMHO more relevant in closed source projects, instead of a RTFM we have the
option for a RTFC(ode).
Keep in mind that no Javadoc means no HTML documentation for the public
API...
Just ask yourself when you are in front of a class you just wrote : what
if the user read the HTML generated page and get something like :
http://mina.apache.org/report/trunk/apidocs/org/apache/mina/integration/xbean/StandardThreadPool.html
How useful is this ?
Maybe a quick dependency graph could show us the "hotspots" which are the
classes many others use/depend on - these are the ones which need good
documentation, I'd guess.
Well, don't loose time on checking files one by one as I did. An easier
way to immediately realize what need to be done is to generate the
Javadoc HTML file and watch it. I don't know why I didn't thought about
it before ...
Cheers,
Michael
PS: If the code and the comments disagree, then both are probably wrong.
Ah ah ah ! Excellent ;)
--
--
cordialement, regards,
Emmanuel Lécharny
www.iktek.com
directory.apache.org
