I'm sure we all appreciate the benefits of good javadoc(!) I've just
committed back some stuff where I've made corrections in this regard. I
just thought I'd point out a few things I noticed.
* I think some IDEs output @todo as a tag within the javadoc section.
However, it is not a standard tag and thus javadoc generates a warning.
Arguably (IMHO) it shouldn't appear in the javadoc section at all and is
better placed as a standard (single / multi-line) comment within the
method / class body itself.
* the @author tag is only supported for the class body itself. On a
similar note, it was agreed at the last developers meeting that we were
not going to have institutional adornments in the javadoc. Therefore the
only 'authorship' is provided via the @author tag. Whether your addition
of a single method merits an addition of yourself to the *class*
authorship is, I guess, a judgment call on you part! (There are
currently no WeblLearn adornments that generate javadoc warnings, but I
appreciate that they may not have yet all been removed from the code!).
* Once added it is good to run javadoc over your code to check for
errors / warnings and even better check it appears as intended in a web
browser.
* a javadoc comment is output as HTML. Therefore a character such as <
to be escaped with ampersand <.
* for an entry, the first line is a simple sentence describing what the
feature does. This is terminated with a full-stop followed by a space
(this is a requirement of the javadoc breakiterator). This sentence
appears in the top (method summary section) of the javadoc HTML output.
Maybe other people have some ideas?
--
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - +
| Alexis O'Connor, VLE Developer (http://bodington.org) |
| OUCS, 13 Banbury Road, Oxford, OX2 6NN, UK. |
| Tel. +44 (0)1865 283661 |
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - +
|
