JavaDoc conventions

Hi Wyona developers,

what about specifying some JavaDoc conventions?

I would propose that at least every public method that is
committed to CVS should have a documentation that covers all
the effects of the method, even if it is just a getter or setter.
If the parameters and return values are not absolutely
self-explanatory, we should add @param and @return tags.

A comprehensive guide to JavaDoc can be found at
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html.


In my eyes, missing or insufficient JavaDocs are one of the
most frustrating matters when I'm trying to use foreign code.
And badly commented code looks - at least in my eyes - quite
incomplete and not very trustworthy (just a prejudice?).

Recently I noticed that in most cases I start with the JavaDoc
when I'm writing code - sometimes it turns out that I wasn't
really conscious of the purpose of a method :)

What do you think?


Andreas