Exercise 3.2: Generating Documentation and Final Submission

Author

Chuck Nelson

Published

October 26, 2025

1 Purpose

This is the final exercise of the course. You have written, tested, and documented your code. The last step is to generate the professional API documentation from your Javadoc comments and submit your completed project. This exercise walks you through generating the Javadoc website and provides a final checklist to ensure your project is complete and ready for grading.

2 What You’ll Accomplish

By the end of this exercise, you will have:

  • Generated a professional HTML documentation website from your Javadoc comments using Maven.
  • Viewed and navigated your own API documentation.
  • Completed a final project checklist and submitted your work to GitHub Classroom.
  • Program Learning Outcomes (PLOs):
    • 2. Use current tools: You will use the Maven Javadoc plugin and Git for project submission.
    • 6. Maintain environment: You will finalize a project for submission and grading.
  • Course Learning Outcomes (CLOs):
    • 7. Document programs: You will generate external documentation from your internal comments.
Learning Objective O*NET KSAs Technologies Used
Generate HTML documentation using the Maven Javadoc plugin. Skills: Communication, Attention to Detail Documentation and support software: Javadoc, Apache Maven
Prepare and submit a final project using Git and GitHub. Skills: Following Instructions Version control software: Git, GitHub Classroom

3 From Comments to a Website

The Javadoc comments you wrote in the previous exercise are not just for reading in the source code. Their real power comes from the Javadoc tool, which reads your .java files and generates a complete HTML website documenting your application’s API (Application Programming Interface).

3.1 Configure Javadoc

The Javadoc documentation in this exercise is produced in two useful forms: a compressed Javadoc JAR (useful for distribution) and an expanded set of HTML files you can publish (for example, in a docs/ folder in your repository or as part of the Maven target site). To have Maven run the Javadoc goals and place outputs where you can commit them, add a plugin configuration like the snippet below to the <plugins/> element of your pom.xml.

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.6.3</version>
        <configuration>
          <show>public</show>
          <nohelp>true</nohelp>
          <outputDirectory>${project.basedir}/docs/apidocs</outputDirectory>
        </configuration>
        <executions>
          <execution>
            <id>attach-javadocs</id>
            <goals>
              <goal>jar</goal>
            </goals>
            <configuration>
              <jarOutputDirectory>${project.basedir}/dist</jarOutputDirectory>
            </configuration>
          </execution>
          <execution>
            <id>generate-docs-apidocs</id>
            <phase>package</phase>
            <goals>
              <goal>javadoc</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>

Notice we specified a <jarOutputDirectory/> element in the execution configuration so the javadoc JAR is written to a top-level dist/ folder (which makes it easy to commit or download). By default Maven writes build outputs to the target/ folder, which is commonly ignored in .gitignore. If you point the expanded HTML apidocs to ${project.basedir}/docs/apidocs they will also be outside target/ and can be committed and served with GitHub Pages.

3.2 Generate and view the Javadoc Website

Maven can generate the Javadoc in expanded HTML form or packaged as a JAR. The simplest way to generate the expanded HTML is to run:

mvn javadoc:javadoc

When the goal completes you should see BUILD SUCCESS.

Where the expanded HTML appears depends on the plugin configuration. Since you configured <outputDirectory>${project.basedir}/docs/apidocs</outputDirectory>, the generated site will be at docs/apidocs/index.html (this is convenient for committing and publishing via GitHub Pages).

To view the documentation locally, open the appropriate index.html in your web browser (for example docs/apidocs/index.html or target/site/apidocs/index.html).

You will see a professional documentation website. Click a class (for example TaskManager or Task) to see detailed documentation for methods, parameters, return values, and exceptions.

This is the standard format for Java library documentation you will encounter throughout your career.

4 Packaging

4.1 Configure JAR packaging

Maven can package your compiled classes and metadata into a Java Archive (JAR) file for distribution. The maven-jar-plugin configuration below writes the produced JAR to a dist/ folder and adds a Main-Class manifest entry so the JAR is runnable with java -jar if it has no external dependencies.

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>3.2.2</version>
        <configuration>
          <outputDirectory>${project.basedir}/dist</outputDirectory>
          <archive>
            <manifest>
              <mainClass>edu.pstcc.citc.App</mainClass>
            </manifest>
          </archive>
        </configuration>
      </plugin>

Notice the <outputDirectory/> element again: it sends the JAR for the compiled application to the dist folder so it can be easily distributed. The JAR created by the maven-jar-plugin contains your compiled classes and a manifest; it does not, by default, include external dependencies.

If your project depends on external libraries and you want a single runnable (“fat” or “uber”) JAR that includes those dependencies, use a shading or assembly plugin such as the maven-shade-plugin. A short note:

  • maven-jar-plugin: creates a JAR with your classes and manifest. Use java -jar only when no external dependencies are required on the classpath or when they are provided by the environment.

  • maven-shade-plugin or maven-assembly-plugin: package your classes and dependencies into a single executable JAR.

Example: to produce an executable fat jar, add and configure the maven-shade-plugin (not shown here) or consult the plugin documentation.

4.2 Creating the JAR

To build the application JAR (and to run the configured javadoc executions), run from the project root:

mvn package

If the build succeeds, check the dist/ directory for the application JAR and the Javadoc JAR.

5 Final Project Submission Checklist

This is it! You are ready to submit your final project. Follow these steps carefully to ensure your submission is complete.

5.1 Add and Commit All Changes

Now, you need to add all your new and modified files to Git version control and commit them with a descriptive message.

  1. Stage all files: This command adds your source code, test code, and even the newly generated Javadoc to the staging area.

    git add .

  2. Commit the files: Commit the staged files with a clear message that summarizes the work you have completed for the final milestone.

    git commit -m "feat: Complete Milestone 3 with tests and Javadoc"

5.2 Step 3: Push to GitHub

The final step is to push your local commits to the remote repository on GitHub Classroom. This makes your work visible to your instructor for grading.

git push

Once the push is complete, you can visit your repository on the GitHub website to see all your files, including the new tests and documentation. You have successfully completed the project!

6 Reflect and Review

ImportantFinal Reflection

In your Microsoft Teams Student Notebook, create a final entry for the course project. Reflect on the entire journey, from the first “Hello, World!” to this final submission. Answer the following:

  • What were the 3 most important skills you learned during this project?
  • What were the 2 most challenging parts of the project for you, and how did you overcome them?
  • What is 1 piece of advice you would give to a future student starting this course?

Congratulations on completing the Introduction to Programming course project!

Back to top