[Bodington-developers] Javadoc

[Alexis O'C. <ale...@co...>]

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 &lt;.

* 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                               |
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - +