Exercise 1.3: Generating Javadoc Documentation

Author

Chuck Nelson

Published

September 8, 2025

Here are the instructions for Exercise 1.3, extracted from the student_exercises.qmd file.

1 Generating Javadoc Documentation

Note

Javadoc is a documentation generator that creates HTML pages from special comments in your Java source code. It’s the standard way to document Java APIs.

In this exercise, you’ll learn how to add Javadoc comments to your code and generate a complete documentation website for your project.

Add Javadoc Comments to your Code

Open src/main/java/com/example/helloworld/App.java and add a class-level Javadoc comment and update the main method comment as shown below.

package com.example.helloworld;

/**
 * A simple application that prints a personalized greeting to the console.
 * This class demonstrates the use of command-line arguments and Maven.
 */
public class App {
  /**
   * Main method that prints Hello World or a personalized greeting based on
   * a command-line argument.
   *
   * @param args Command-line arguments provided at runtime.
   * If an argument is provided, it will be used as the name.
   */
  public static void main(String[] args) {
    String name;
    if (args.length > 0) {
      name = args[0];
    } else {
      name = "World";
    }
    System.out.println("Hello, " + name + "!");
  }
}

Next, open src/test/java/com/example/helloworld/AppTest.java and add Javadoc comments to your test methods.

package com.example.helloworld;

import static org.junit.jupiter.api.Assertions.assertEquals;
import org.junit.jupiter.api.Test;
import java.io.ByteArrayOutputStream;
import java.io.PrintStream;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;

public class AppTest {
  private final ByteArrayOutputStream outContent = new ByteArrayOutputStream();
  private final PrintStream originalOut = System.out;

  @BeforeEach
  public void setUpStreams() {
    System.setOut(new PrintStream(outContent));
  }

  @AfterEach
  public void restoreStreams() {
    System.setOut(originalOut);
  }

  /**
   * Tests that the application prints the correct greeting when a command-line
   * argument is provided.
   */
  @Test
  public void testAppPrintsCorrectOutputWithArgument() {
    String expectedOutput = "Hello, TestUser!\n";
    App.main(new String[]{"TestUser"});
    assertEquals(expectedOutput, outContent.toString());
  }

  /**
   * Tests that the application prints the default greeting when no command-line
   * argument is provided.
   */
  @Test
  public void testAppPrintsCorrectOutputWithoutArgument() {
    String expectedOutput = "Hello, World!\n";
    App.main(new String[]{});
    assertEquals(expectedOutput, outContent.toString());
  }
}

Generate the Javadoc Documentation

Run the following command in your terminal to generate the HTML documentation:

mvn javadoc:javadoc
Important

Did you notice the warning in the output?

[WARNING] Javadoc 1.4+ doesn't support the -1.1 switch anymore. Ignore this option.

Let’s clear that up.

Missing Plugin Configuration

The -1.1 switch was used to generate Javadoc documentation compatible with the very early days of Java, specifically Java 1.1. As Javadoc and the Java language have evolved, this option has become obsolete. Newer versions of the Javadoc tool, including those in JDK 1.4 and later, do not recognize or support it.

Even though it’s a warning and your build still succeeds, it’s a good idea to fix it to clean up your build output and prevent potential issues with future JDK or Maven plugin updates.

How to Fix It

The fix is to check the configuration in your pom.xml file. The -1.1 switch is often found within the section of the maven-javadoc-plugin definition.

Open your pom.xml file.

Look for the maven-javadoc-plugin section. In our example project, it does not yet exist. Lets add the plugin section to our exisitng pom.xml file.

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.6.0</version>
        <configuration>
          <source>21</source>
        </configuration>
      </plugin>

Delete the line containing the -1.1 switch. The line will likely be 1.1, but it could be another tag like or .

Save the pom.xml file.

The javadoc execution should now execute without that warning.

Missing Implicit Constructor Documentation

The warning about an unsupported switch is gone, but now there are new warnings.

[WARNING] Javadoc Warnings
[WARNING] /home/chuck/PSCC/Courses/CITC_1310-Programming_I/JavaProjects/JavaToolchain/hello-world/src/main/java/com/example/helloworld/App.java:7: warning: use of default constructor, which does not provide a comment
[WARNING] public class App {
[WARNING] ^
[WARNING] 1 warning

This warning means that a class in your code, App.java, has a default constructor (one you didn’t explicitly write) that lacks Javadoc comments. Javadoc’s purpose is to generate API documentation, and it warns you about any public or protected members that are missing comments, including the default constructor.

How to Fix It

Explicitly define the constructor and add a Javadoc comment. This is a best practice for API documentation.

Update the App class to have an explicit constructor and add javadoc comments as inthe following code.

package com.example.helloworld;

public class App {

    /**
     * Constructs an instance of the App class.
     */
    public App() {
        // Default constructor logic goes here (usually empty).
    }
    
    // Your methods go here...
    
}

By adding Javadoc comments, you provide meaningful documentation for your code, which is a best practice for any public API. Once you’ve added the Javadoc, run mvn javadoc:javadoc again, and the warning should disappear.

mvn javadoc:javadoc

All documentation should generate without errors or warnings now.

[INFO] Scanning for projects...
[INFO] 
[INFO] -----------------< com.example.helloworld:hello-world >-----------------
[INFO] Building hello-world 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] >>> javadoc:3.6.0:javadoc (default-cli) > generate-sources @ hello-world >>>
[INFO] 
[INFO] <<< javadoc:3.6.0:javadoc (default-cli) < generate-sources @ hello-world <<<
[INFO] 
[INFO] 
[INFO] --- javadoc:3.6.0:javadoc (default-cli) @ hello-world ---
[INFO] Configuration changed, re-generating javadoc.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  0.710 s
[INFO] Finished at: 2025-09-08T16:40:37-04:00
[INFO] ------------------------------------------------------------------------

View the Documentation

Once the command completes, you’ll find the generated documentation in the target/site/apidocs directory.

Open target/site/apidocs/index.html in your web browser using the VS Code Live Server extension to view the documentation. Just find the file in the VS Code Explorer (Ctrl+Shift+E), right click on it, and choose Open with Live Server.

Back to top