Writing Javadoc Comments - touniez/comp402doc GitHub Wiki

In general, Javadoc comments are any multi-line comments ("/** ... */") that are placed before class, field, or method declarations. They must begin with a slash and two stars, and they can include special tags to describe characteristics like method parameters or return values. The HTML files generated by Javadoc will describe each field and method of a class, using the Javadoc comments in the source code itself. Examples of different Javadoc comments are listed below.

Normal Javadoc comments can be placed before any class, field, or method declaration to describe its intent or characteristics. For example, the following simple Student class has several Javadoc comments.

 /** * Represents
          a student enrolled in the school.  * A student can be enrolled in
          many courses.  */ public class Student {

  /** * The first and last name of this student.  */ private String name;

  /** * Creates a new Student with the given name.  * The name should include
  both first and * last name.  */ public Student(String name) { this.name =
  name; }

} 

Tags can be used at the end of each Javadoc comment to provide more structured information about the code being described. For example, most Javadoc comments for methods include "@param" and "@return" tags when applicable, to describe the method's parameters and return value. The "@param" tag should be followed by the parameter's name, and then a description of that parameter. The "@return" tag is followed simply by a description of the return value. Examples of these tags are given below.

 /** * Gets the
          first and last name of this Student.  * @return this Student's name.
          */ public String getName() { return name; }

  /** * Changes the name of this Student.  * This may involve a lengthy legal
  process.  * @param newName This Student's new name.  *                Should
  include both first *                and last name.  */ public void
  setName(String newName) { name = newName; } 

Other common tags include "@throws e" (to describe some Exception "e" which is thrown by a method) and "@see #foo" (to provide a link to a field or method named "foo").