Documentation Comments - Javadoc

Javadoc is a tool for generating documentation and comes with JDK. The documentation is written as comment section s that follow a predefined format. Many IDEs know how to generate the documentation as HTML based on the Javadoc comments. For example, in NetBeans is it possible to run Generate Javadoc by right-clicking the project window or from the menu Run->Generate Javadoc

Basic structure of Javadoc comments

The documentation is written into the code as Javadoc comments using the stnadard /*  */ comment block so that the opening comment delimiter has an extra * in it i.e. the Javadoc comment block is written between the /** */ delimiters. The comment block is structured as follows. In the texts in the documentation HTML tags such as <p> can be used:

• As the class level comment the documentation is written before public class Name and after the import statements a description of the entire class. Typically the block contains tags:

  • @author for the author information

  • @version the current version of the program. In addition @since that is turn tells the version when the class was added into the program

For each method a documentation is written where:

• The first paragraph describes the method

• The description is followed by a group of tags that describe a varied amount of things for the method. For example:

  • @param for the parameters of the method

  • @return for the return value

  • @throws all possible exceptions thrown by the method

For example:

/**
 * a simple data class that represents a point in two-dimensional space
 * <p>
 * @author N.N.
 * @since 1.0
 */

 public class Point2D {
    /**
     * value on the x dimension
     */
    private double x;

    /**
     * value of the y dimension
     */
    private double y;

    /**
     * A constructor that takes X and Y as parameters
     * @param x Initial value of X
     * @param y Initial value of Y
     */
    public Point2D(double x, double y) {
        this.x = x;
        this.y = y;
    }

    /**
     * A second constructor that does not take parameters.
     * The result is like Point2D(0, 0).
     */
    public Point2D() {
        this(0, 0);  // A constructor can call another constructor by using the this reference.
    }

    /**
     * Returns the value of X
     * @return double X:n arvo
     */
    public double getX() {
        return x;
    }

    /**
     * Sets a new value to X
     * @param x New value to X
     * @return Nothing
     */
    public void setX(double x) {
        this.x = x;
    }

To generate documentation for a package a file package-info.java needs to be created into the package directory. In it before the package declaration a comment block containing the description of the package is written. For example:

/**
 * Provides the classes needed for Programming 3 exercise JSON
 * <p>
 * @author N.N.
 * @since 1.0
 */
package fi.tuni.programming3;

All tags can be found here.

Posting submission...