Guided Task: Generate Javadoc

Commenting your code is important! Comments describe what the code is supposed to do. At a minimum, you should comment all your classes, fields, and methods. All methods should be Javadoc-ed, including methods that were automatically generated by Eclipse. This is because you should provide the client of your code details about why you overrode the method and the specific overridden functionality! When working with CSC 216/217 projects, you should delete any automatically generated non-Javadoc documentation and replace it with Javadoc appropriate for the overridden method.

Java provides the Javadoc tool to generate a set of web pages that display the comments for your code.

Every time you use the Java API, you are using web pages generated with the Javadoc tool. The Java developers have done an excellent job of commenting the class files in the Java SDK. You can use the API to find classes and methods that may help you implement the program you’re writing. You should return the favor to those who may use your code (as well future you) by writing comments. By writing the comments in a Javadoc format, you’ll be able to generate an API for your code that will benefit future programmers.

Learning Outcomes

Generate Javadoc API pages for WolfScheduler

Check your Comments

Javadoc Requirements and @author Tag

Javadoc Expectations

Your Javadoc comments must include:

Class-level comments with an @author tag:

   /**
    * Represents a course with name, title, section, credits, instructor, and meeting information.
    * 
    * @author Your Name (yourunityid)
    */
   public class Course {

The @author tag is required to pass CheckStyle analysis. Replace “Your Name” with your actual name and “yourunityid” with your unity ID.

Method-level comments for ALL methods, including:
- Getters and setters (even if auto-generated)
- Constructors
- Overridden methods like equals(), hashCode(), and toString(). Provide details on the override.
- All helper methods
Field-level comments for ALL fields (already included in the provided code)
Exception comments are required for all methods and constructors that can throw an exception. This includes when the method or constructor calls another method or constructor that could throw an exception. For example, the Course constructors call setter methods that throw IllegalArgumentExceptions. Course’s constructors don’t handle those exceptions, instead they throw them to the caller. Your Javadoc should reflect this!

Do not leave auto-generated comments unchanged. Eclipse often generates placeholder comments like “TODO Auto-generated method stub” or generic descriptions. Replace these with meaningful descriptions of what YOUR implementation does.

Double check your Javadoc comments. Are they correct? Do they describe the functionality of methods, fields, and classes? Are you missing any key items? The CheckStyle static analysis tool can help you find most missing items in your Javadoc, but not all (e.g., missing @throws tags on methods that throw unchecked exceptions like IllegalArgumentException). Make sure that you have resolved all notifications from CheckStyle.

The teaching staff (actual people) do read your comments to ensure they are appropriate for the classes, fields, and methods. Please do not include anything that would be considered inappropriate (e.g., no bad language; no disparaging remarks about you, your classmates, the teaching staff, or the class; no threatening or offensive text).

Configure and Run Javadoc for your Project

After you have written your Javadoc in your class files, you can run the Javadoc tool on your code by selecting Project > Generate Javadoc.

In the resulting dialog, you must configure the Javadoc command if you have not already done so. To configure Javadoc, click Configure. Browse to the location where you installed your JDK. The javadoc tool is in the bin folder.

Additionally, you can select which projects/packages/classes/and files you want to run Javadoc on. Most of the time, you only want to generate Javadoc for classes in the source folder since they represent a deliverable that others may use.

Check the option to Use standard doclet. Browse for your project as the destination and then append a doc folder to the end of the path.

Javadoc Checks!

Make sure that you browse to your current project’s location! The Javadoc tool remembers locations from other projects. You don’t want to generate your Javadoc in the wrong location!

Always verify that your generated Javadoc is in your project AND that the generated Javadoc is pushed to the correct GitHub repository via the browser!

Click Next and Next. On the third menu, ensure that the JRE Source Compatibility is set to 21.

Figure: Generate Javadoc JRE Source Compatibility

Click Finish to generate the Javadoc. If your project does not already have a doc folder, Eclipse prompts you to create the destination folder. Click Yes To All.

When the Javadoc has been created, refresh your project listing in the Package Explorer if it has not been done automatically. You can do this by selecting your project and pressing F5. Your project should now show a doc directory.

Fix Javadoc Errors and Warnings

Console output is generated when creating Javadoc. You should scroll back through the output to see if there are any errors or warnings that you need to fix. An example warning about a missing description on a @throws tag is shown. There’s also a warning: use of default constructor, which does not provide a comment for CourseRecordIO. You can ignore the warning about the use of the default constructor for CourseRecordIO - all the methods are static. Fix any other warnings.

Check Generated Javadoc Pages

You can view your Javadoc by opening the index.html within the doc directory. When you open an *.html file inside Eclipse, a browser will be opened in the Eclipse editor showing your newly generated Javadoc. If a browser isn’t opened, you can right click on the file and select Open With > Browser.

Any time you update your Javadoc, you should regenerate the HTML files!

Always select the entire src/ folder. Sometimes the javadoc tool will only run on the currently selected class! Double check that the correct files were created! Push all the changes to GitHub.

Push Javadoc to GitHub

After generating your Javadoc, you must push the generated documentation to GitHub as part of your submission.

Files to Push:

The entire doc/ directory and all its contents, including:
- index.html (main entry point)
- All generated .html files for your classes
- All subdirectories (e.g., edu/ncsu/csc216/wolf_scheduler/course/)
- Supporting files (.css, .js, images)
How to verify before pushing:
- In Eclipse’s Package Explorer, expand the doc/ folder
- You should see index.html and multiple subdirectories with .html files
- If you only see a few files or the folder is empty, re-run the Javadoc generator
Staging and committing:
- Stage the entire doc/ directory: git add doc/
- Or in Eclipse: right-click doc/ folder > Team > Add to Index
- Commit with message like: “[Documentation] Generated Javadoc”
- Push to GitHub
Verification on GitHub:
- After pushing, navigate to your repository on github.ncsu.edu
- Verify the doc/ directory exists with all subdirectories and files
- Click through to doc/index.html to confirm the structure is intact

Important: Push Complete Javadoc

Common Mistake: Students sometimes forget to add the doc/ folder to Git or only push index.html. The teaching staff needs the complete Javadoc directory structure to grade your documentation. Missing Javadoc files will result in point deductions.

Check Your Progress

Before moving on to the next portion of the Guided Project, complete the following tasks:

Make sure that all fields, methods, and constructors are commented.
Resolve all static analysis notifications.
Fix test failures.
Commit and push your code changes with a meaningful commit message. Label your commit with “[Documentation]” for future you!

Guided Project 1 - Software Development Practices and Tools