Javadoc: Generating and Writing Documentation

Javadoc is the standard tool for documenting Java code. It reads specially formatted comments from your source files and generates HTML documentation that looks and works like the official Java API docs.

Javadoc is assessed on all work in this course. This page explains how to generate it, what is required, and how to fix common problems.

Note about this page

Some of the concepts below you may not yet be familiar with; we will be covering more javadoc tags this semester.

Generating Javadoc

Run this command from your projects directory:

ant jdoc

This compiles your documentation comments and produces a set of HTML files you can open in a browser.

Generated HTML files are saved in the docs/ folder. Open docs/index.html in your browser to view the generated documentation.

Always review the generated HTML

Running ant jdoc with no warnings does not guarantee good documentation. Open docs/index.html and browse your class pages to verify that your descriptions are readable and complete. If it looks wrong in the browser, it will look wrong to your instructor.

How to View JavaDoc in Your Browser (3:51)

What Must Be Documented

Classes

Every class requires a Javadoc comment that includes:

A description of what the class does
@author with your name
@version with a version number or date

/**
 * Analyzes a text file and computes student statistics.
 * Students are defined as whitespace-delimited strings.
 *
 * @author Kari Schumacher
 * @version 1.0
 */
public class StudentAnalyzer implements Analyzer {

Constructors

Every constructor requires:

A description of what the constructor does (what it initializes)
@param for each parameter (if applicable)
@throws for any checked exceptions (if applicable)

/**
 * Creates a new FileReviewer and initializes the file to analyze.
 *
 * @param filename the path to the file to analyze
 * @throws IOException if the file cannot be opened
 */
public FileReviewer(String page) throws IOException {

Public Methods

Every public method requires:

A description of what the method does
@param for each parameter (if applicable)
@return if the method returns a value (not needed for void)
@throws for any checked exceptions (if applicable)

Instance Variables

Every instance variable (field) should have a brief comment describing its purpose.

/** The total number of students read from the input file. */
private int studentCount;

/** A set containing each unique student encountered. */
private Set<String> uniqueStudents;

Before and After Example

Before: Undocumented

public int countStudents(String filename) {
    // implementation
}

This generates a Javadoc warning and provides no information to anyone reading the code, including you six weeks from now.

After: Fully Documented

/**
 * Counts the total number of students in the specified file.
 * A student is any whitespace-delimited string.
 *
 * @param filename the path to the input file
 * @return the total number of students found in the file
 * @throws IOException if the file cannot be read
 */
public int countStudents(String filename) throws IOException {
    // implementation
}

The documented version tells a reader:

What the method does
What a "student" means in this context
What to pass in
What to expect back
What can go wrong

This is the level of documentation expected in all course work.

Javadoc Tag Reference

Tag	When to Use	Example
`@author`	Once per class, identifies who wrote it	`@author Kari Schumacher`
`@version`	Once per class, identifies the version or date	`@version 1.0`
`@param`	Once per method parameter	`@param filename the path to the input file`
`@return`	When a method returns a non-void value	`@return the total student count`
`@throws`	When a method throws a checked exception	`@throws IOException if the file cannot be read`
`@see`	To link to a related class or method	`@see StudentAnalyzer`
`@since`	To indicate when a method or class was added	`@since 1.1`

Writing Good Tag Descriptions

Each tag description should tell a reader something useful. Avoid restating the parameter name.

Too little	Just right
`@param filename filename`	`@param filename the path to the input file`
`@return result`	`@return the total number of students found`
`@throws IOException exception`	`@throws IOException if the file cannot be opened or read`

Comment Structure

A Javadoc comment starts with /** and ends with */. The content has two parts:

Description block: The text before any tags. The first sentence is treated specially: it appears in summary tables throughout the generated HTML. Make it complete and informative on its own.
Tag block: All the @param, @return, @throws, and other tags, listed after a blank line.

/**
 * Returns the number of unique students found in the file.        <- first sentence (summary)
 * Unique students are compared in a case-insensitive manner.      <- additional description
 *
 * @return the count of distinct students                          <- tag block starts after blank line
 */
public int getUniqueStudentCount() {

You can use basic HTML in descriptions when needed. For example, <p> starts a new paragraph, and <code> formats inline code:

/**
 * Reads students from the input file and stores them for analysis.
 * Call this method before calling any get methods.
 *
 * <p>If the file has already been read, calling this method again
 * resets all counters and re-reads the file.</p>
 *
 * @param filename the path to the input file
 * @throws IOException if the file cannot be opened
 */

Understanding Warning Messages

When you run ant jdoc, any missing or malformed documentation appears as a warning in the terminal. Here are the most common ones.

Missing `@return`

warning: no @return
    public int countStudents(String filename) {
                ^

What it means: The method returns a value but has no @return tag.

How to fix it: Add a @return tag to the Javadoc comment describing what the method returns.

/**
 * Counts the total number of students in the file.
 *
 * @param filename the path to the input file
 * @return the total number of students found
 */
public int countStudents(String filename) {

Missing `@param`

warning: no @param for filename
    public int countStudents(String filename) {

What it means: The method has a parameter named filename but the Javadoc comment does not document it.

How to fix it: Add a @param tag for each parameter. The name in the tag must match exactly.

/**
 * Counts the total number of students in the file.
 *
 * @param filename the path to the input file
 * @return the total number of students found
 */

Missing class or method description

warning: no comment
    public void performAnalysis(String filePath) {

What it means: The method (or class) has no Javadoc comment at all.

How to fix it: Add a /** ... */ comment above the method or class declaration.

Parameter name mismatch

warning: @param "file" not found
    public int countStudents(String filename) {

What it means: The @param tag uses a name that does not match any parameter in the method signature.

How to fix it: Check that the name in your @param tag matches the parameter name in the method signature exactly. Capitalization matters.

Missing `@throws`

warning: no @throws for IOException
    public void loadFile(String filePath) throws IOException {

What it means: The method declares a checked exception in its signature but does not document it.

How to fix it: Add a @throws tag describing when the exception occurs.

/**
 * Loads and reads the specified file.
 *
 * @param filePath the path to the file
 * @throws IOException if the file cannot be found or read
 */
public void loadFile(String filePath) throws IOException {

Tips for Getting a Clean Run

Follow these steps when you have multiple warnings to fix:

Fix warnings from top to bottom. Earlier warnings can sometimes cause later ones. Work through the output in order.
Re-run ant jdoc after each fix. This keeps the warning list accurate and prevents confusion about which problems remain.
Check every public method and constructor. Private methods do not need Javadoc, but every public method does.
Verify parameter names match exactly. Copy the parameter name from the method signature and paste it into your @param tag to avoid typos.
Do not leave placeholder text. Descriptions like "does stuff" or "param param" will not earn credit. Write descriptions that actually explain behavior.
Add @version to every class. A version number or date is required on class-level comments. 1.0 is a fine starting value.
Open the generated HTML and read it. A clean ant jdoc run with no warnings is the minimum requirement. The documentation also needs to make sense. Browse your class pages in the browser to confirm.

What Good vs. Poor Javadoc Looks Like

Too vague:

/**
 * Does stuff.
 */
public void performAnalysis(String filePath) {

Technically present but useless:

/**
 * This method is a method that performs an analysis of things
 * by analyzing them. It takes a filePath parameter.
 *
 * @param filePath filePath
 */
public void performAnalysis(String filePath) {

Clear and complete:

/**
 * Reads students from the input file, stores unique students in a set,
 * and records the total count.
 *
 * @param filePath the path to the input file
 * @throws IOException if the file cannot be read
 */
public void performAnalysis(String filePath) throws IOException {

The goal is documentation that helps a teammate understand your code without reading the implementation.

AI and Javadoc

AI can draft Javadoc, but you must review it

AI tools can generate Javadoc comments from your method signature. This can save time on boilerplate, but AI-generated Javadoc has common failure modes:

@param descriptions often just restate the parameter name (filePath: the file path)
@return descriptions are often vague (returns the result)
AI may miss edge cases or conditions that matter to callers

Use AI-generated Javadoc as a first draft, then edit it to accurately describe what your method actually does. The goal is documentation that helps a teammate, not documentation that just passes a lint check.