Using JavaDoc to Document Your Classes

Introduction

JavaDoc comments begins with /** and end with */.

You can place JavaDoc comments in any of three different locations in a source file:

Immediately before the declaration of a public class
Immediately before the declaration of a public field
Immediately before the declaration of a public method or constructor

Commonly Used JavaDoc Tags

Tag	Explanation
@author	Provides information about the author, typically the author's name, e-mail address, Web site information, and so on.
@version	The version number.
@since	Used to indicate the version with which this class, field, or method was added.
@param	Provides the name and description of a method or constructor parameter.
@return	Provides a description of a method's return value.
@throws	Indicates exceptions that are thrown by a method or constructor.
@deprecated	Indicates that the class, field, or method is deprecated and shouldn't be used.

package com.book2s;

/**
 * Represents an employee.
 *
 * @author Your Name
 * @author www.java2s.com
 * @version 1.5
 * @since 1.0
 */
public class Employee implements Cloneable {
  private String lastName;
  private String firstName;
  private Double salary;

  /**
   * Represents the employee's address.
   */
  public Address address;

  /**
   * Creates an employee with the specified name.
   *
   * @param lastName
   *          The employee's last name.
   * @param firstName
   *          The employee's first name.
   */
  public Employee(String lastName, String firstName) {
    this.lastName = lastName;
    this.firstName = firstName;
    this.address = new Address();
  }

  /**
   * Gets the employee's last name.
   *
   * @return A string representing the employee's last name.
   */
  public String getLastName() {
    return this.lastName;
  }

  /**
   * Sets the employee's last name.
   *
   * @param lastName
   *          A String containing the employee's last name.
   * @return No return value.
   */
  public void setLastName(String lastName) {
    this.lastName = lastName;
  }

  /**
   * Gets the employee's first name.
   *
   * @return A string representing the employee's first name.
   */
  public String getFirstName() {
    return this.firstName;
  }

  /**
   * Sets the employee's first name.
   *
   * @param firstName
   *          A String containing the employee's first name.
   * @return No return value.
   */
  public void setFirstName(String firstName) {
    this.firstName = firstName;
  }

  /**
   * Gets the employee's salary.
   *
   * @return A double representing the employee's salary.
   */
  public double getSalary() {
    return this.salary;
  }

  /**
   * Sets the employee's salary.
   *
   * @param lastName
   *          A double containing the employee's salary.
   * @return No return value.
   */
  public void setSalary(double salary) {
    this.salary = salary;
  }

  /**
   * Creates a deep copy of the employee object.
   *
   * @return A cloned Employee object. Note that you must explicitly cast this
   *         object to Employee.
   */
  public Object clone() {
    Employee emp;
    try {
      emp = (Employee) super.clone();
      emp.address = (Address) address.clone();
    } catch (CloneNotSupportedException e) {
      return null; // will never happen
    }
    return emp;
  }

  /**
   * Returns a String representation of the employee. That includes the name of
   * the class, the employee's first and last name, and the salary.
   *
   * @return A String representation of the employee.
   */
  public String toString() {
    return this.getClass().getName() + "[" + this.firstName + " " + this.lastName + ", " + this.salary + "]";
  }

  /**
   * Compares this employee with another employee. 
   *
   * @return A boolean that indicates whether the employees are equal.
   */
  public boolean equals(Object obj) {
    // an object must equal itself
    if (this == obj)
      return true;

    // no object equals null
    if (this == null)
      return false;

    // objects of different types are never equal
    if (this.getClass() != obj.getClass())
      return false;

    // cast to an Employee, then compare the fields
    Employee emp = (Employee) obj;
    return this.lastName.equals(emp.getLastName()) && this.firstName.equals(emp.getFirstName());
  }
}

Using the javadoc command

Specify the complete path to all the Java files you want to create documentation for, like this:

javadoc com\book2s\*.java

Using JavaDoc to Document Your Classes - Java Language Basics

Introduction

Using the javadoc command

Related Tutorials