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
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 missing items in your Javadoc. 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 11.
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. Fix any warnings or errors and regenerate.
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.
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.
Reference: Staging and Pushing to GitHub
GitHub Resources:
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!