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

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...