Exercise 3.1: Documenting Code with Javadoc

Author

Chuck Nelson

Published

October 25, 2025

1 Purpose

Writing code that works is only half the battle. Writing code that others (and your future self) can understand is just as important. Professional developers document their code to explain its purpose, how to use it, and why certain decisions were made. In Java, the industry standard for this is Javadoc.

This exercise will teach you how to write Javadoc comments, which are special comments that can be automatically processed by tools to generate professional API documentation.

2 What You’ll Accomplish

By the end of this exercise, you will have:

  • Understood the syntax and purpose of Javadoc comments.
  • Used Javadoc tags like @param, @return, and @throws to document methods.
  • Documented all the public classes and methods in your task management application.
  • Program Learning Outcomes (PLOs):
    • 2. Use current tools: You will use the Javadoc standard and associated tooling.
    • 5. Implement solutions: You will produce a well-documented Java application.
  • Course Learning Outcomes (CLOs):
    • 7. Document programs: This exercise is entirely focused on creating internal and external program documentation.
Learning Objective O*NET KSAs Technologies Used
Write Javadoc comments for classes and methods. Skills: Communication, Reading Comprehension
Abilities: Written Expression		 Documentation and support software: Javadoc
Use Javadoc tags to describe parameters, returns, and exceptions. Skills: Attention to Detail Object or component oriented development software: Java

3 What is Javadoc?

Javadoc comments are more than just regular comments. They follow a specific format that starts with /** and ends with */. Inside these comments, you can use special tags (prefixed with @) to provide structured information about your code.

IDEs like VS Code have excellent Javadoc support. If you type /** above a method and press Enter, the IDE will often automatically generate a template for you with the necessary tags.

3.1 Javadoc Syntax

A Javadoc comment consists of two parts:

  1. Description: A brief, clear sentence describing the purpose of the class or method.
  2. Block Tags: Special tags that describe specific elements.

Common tags include: - @param <name> <description>: Describes a method parameter. - @return <description>: Describes the method’s return value. - @throws <ExceptionType> <description>: Describes an exception that the method may throw. - @author <name>: Identifies the author of the class. - @version <version>: Specifies the version of the code.

3.2 1. Documenting a Method

Let’s document the findTaskById method in your TaskManager.java file. This is a great example because it has a parameter, a return value, and throws an exception.

Here is the method without documentation:

// In TaskManager.java
public Task findTaskById(int taskId) throws TaskNotFoundException {
  for (Task task : taskStore) {
    if (task.getId() == taskId) {
      return task; // Found it!
    }
  }
  throw new TaskNotFoundException("Task with ID " + taskId + " could not be found.");
}

Now, here is the same method with a complete Javadoc comment:

// In TaskManager.java

/**
 * Finds a task by its unique identifier.
 *
 * @param taskId The ID of the task to find.
 * @return The found Task object.
 * @throws TaskNotFoundException if no task with the given ID exists in the store.
 */
public Task findTaskById(int taskId) throws TaskNotFoundException {
  for (Task task : taskStore) {
    if (task.getId() == taskId) {
      return task; // Found it!
    }
  }
  throw new TaskNotFoundException("Task with ID " + taskId + " could not be found.");
}

This comment clearly explains what the method does, what input it expects, what it returns, and what errors it might produce. This is invaluable information for anyone using this method.

3.3 2. Documenting a Class

You should also document your classes. A class comment provides a general overview of the class’s purpose.

package edu.pstcc.citc;

import java.util.ArrayList;
import java.util.List;

/**
 * Manages the lifecycle of tasks, including creation, retrieval, and deletion.
 * This class uses an in-memory list to store tasks.
 * 
 * @author Your Name
 * @version 1.0
 */
public class TaskManager {
    // ... class content
}

4 Your Turn: Document Everything

Your task is to go through the project and add Javadoc comments to all public classes and methods. This is a common requirement in professional development.

Here is a checklist of files to document:

For simple getter/setter methods, a short description is sufficient. For example:

/**
 * Gets the title of the task.
 * @return The current title.
 */
public String getTitle() { ... }

Take your time and write clear, concise descriptions. In the next exercise, we will see how to turn these comments into a professional documentation website.

5 Reflect and Review

ImportantReflection: 3-2-1

In your Microsoft Teams Student Notebook, answer the following:

  • 3 Javadoc tags you used in this exercise.
  • 2 reasons why documenting code is important.
  • 1 question you still have about Javadoc or code documentation.
TipCheck on Learning

Answer the following questions in your Microsoft Teams Student Notebook.

  1. What is the primary purpose of Javadoc?
  2. How do you start a Javadoc comment block?
  3. Which Javadoc tag is used to describe a method’s parameter?
  4. If a method can throw an error, which Javadoc tag should you use to document it?
Back to top