Javadoc is
a great tool, and should be used with feelings of unbridled joy ;).

A method header combined with its associated javadoc form the specification,
or contract, of a method. If the caller fulfills the stated requirements,
then the method undertakes to fulfill its stated promises.

Using Javadoc acknowledges that there are two distinct questions a reader can ask about
code:

what is this supposed to do? (answered only by the javadoc and method header)

how does it try to do it? (answered only by the implementation)

If javadoc is written correctly, then:

one can understand exactly what services are offered by a method ("what
is this supposed this do?"), without having to look at its implementation
("how does it try to do it?"). Reading an implementation usually takes a lot
more effort than reading javdoc.

the implementation can be checked for correctness versus the specification. That is, some bugs
can be found just by reading the code, as opposed to executing it.

the -tag option allows user-defined custom tags. This feature
can be used to implement common items such as @to.do, @is.Mutable,
or @no.Nulls. (Oracle recommends placing a period somewhere
in the custom tag, to avoid potential future conflicts with tags defined
by Oracle.)

the -linksource option generates an HTML version of your source
code, and links the javadoc to the source. (The source is presented without
any syntax highlighting, but this remains a very nice feature.)

there is finer-grained control over how javadoc is inherited. The {@inheritDoc}
tag is useful here (warning: this is broken in JDK 1.4.0)

/**
Maintain a list of Members in the Fish and Chips Club.
An Active Member will be part of the RSVP list. When a Member
is inactive, they will not appear on the RSVP listing.
@author B. P. Hennessey
@version 1.0
*/
package hirondelle.fish.main.member;