Document your classes and methods with Javadoc comments and generate a browsable HTML API reference with the javadoc tool.
Why: Javadoc is Java's built-in way to document code. You write special comments above classes and methods, and the javadoc tool turns them into the same browsable HTML reference you see for the standard library itself.
Why: a Javadoc comment starts with /** (two stars) and sits directly above what it describes. The first sentence is the summary. Tags like @param, @return, and @throws document each part of a method.
/**
* Calculates the area of a rectangle.
*
* @param width the width in metres (must be positive)
* @param height the height in metres (must be positive)
* @return the area in square metres
* @throws IllegalArgumentException if either side is negative
*/
public double area(double width, double height) {
if (width < 0 || height < 0)
throw new IllegalArgumentException("sides must be positive");
return width * height;
}When: run the javadoc tool over your sources to produce a docs/ folder of HTML you can open in a browser. Build tools wrap this too (mvn javadoc:javadoc, ./gradlew javadoc).
Generate docs for every .java file under src into a docs folder:
javadoc -d docs src/com/example/*.java