Writing effective documentation
Undocumented code is useless code to anyone other than the developers. On the other hand, excessive documentation explaining even minor details makes code harder to read than helping the developer. All in all, the matter of writing precise and adequate documentation is outside the scope of the book, but is essential to at least provide some general pointers and references.
As you probably already know, Javadoc is the official documentation generation system introduced by Sun Microsystems.
Note
How to write documentation comments for the Javadoc tool
Make sure to visit Oracle's comprehensive Javadoc guide at the following URL:
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
Comments structure
A Javadoc block comment starts with /**
and ends with */
. Lines between the opening and closing tags start with *
. Single line or inline comments start with //
.
Javadoc block comment
/** * Description of Method. * This method is responsible...