- COMP.CS.140
- 10. Work Distribution and Working in a Team
- 10.2 Documentation and Conventions
- 10.2.1 Documentation Comments - Javadoc
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 your own documentation for a package, the package-info.java
file
needs to be created into the package directory. Comments describing of the package
are given before the package declaration. 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.