Activity: Generate a Javadoc from a sample project
Javadoc is the standard output for Java APIs, and it’s really easy to build a Javadoc. The Javadoc is generated through something called a “doclet.” Different doclets can parse the Java annotations in different ways and produce different outputs. But by and large, almost every Java documentation uses Javadoc. It’s standard and familiar to Java developers.
Characteristics of Javadoc
Here are some other characteristics of Javadoc:
- Javadoc is supported by Oracle
- Javadoc’s output integrates directly into IDEs that developers use.
- The Javadoc output is skinnable, but you can’t add non-ref files to it.
- The Javadoc comment style is highly similar to most other document generators.
Generate a Javadoc
- In Eclipse, go to File > Export.
- Expand Java and select Javadoc. Then click Next.
Select your project and package. Then in the right pane, select the classes you want included in the Javadoc. Don’t select the class that contains your main method. In this sample project, the main method is included in App.java.
Select which visibility option you want: Private, Package, Protected, or Public. Generally you select Public.
Your API probably has a lot of helper or utility classes used on the backend, but only a select number of classes will actually be used by your developer audience. These classes are made public. It’s the public classes that your developer audience will use that form the API aspect of the class library.
- Make sure the Use standard doclet radio button is selected (it’s selected by default).
Click the Browse button and select the output location where you want the Javadoc generated. By default, it will be generated in the same project folder as your code, but in a subfolder called doc. This way you can browse the Javadoc directly within your Eclipse IDE.
For this activity, choose a different output location (such as a folder on your desktop or in your documents) other than the default. Reason being, the project already has the generated Javadoc in a docs folder, so you might not even realize that you’ve generated a Javadoc file because your new output will just overwrite the existing doc files.
Here you can select if you want to omit some tags, such as @author and @deprecated. Generally you don’t include the @author tag, since it may only be important internally, not externally. You can also select different options in the Javadoc frame. If you have a custom stylesheet, you can select it here. Most likely you would only make superficial style changes such as with colors.
Here you can select an HTML page that you want to be your overview page in the Javadoc. You can select any HTML page and it will be included in the index.
If prompted to update the Javadoc location (which likely differs from your Eclipse workspace location), do so by clicking Yes to all.
Browse to the destination location and open the index.html file in your browser to view the files.
Javadoc and error checking
Javadoc also checks your tags against the actual code. If you have parameters, exceptions, or returns that don’t match up with the parameters, exceptions, or returns in your actual code, then Javadoc will show some warnings.
Try removing a parameter from a method and generate the Javadoc again. Make sure the console window is open.
87/101 pages complete. Only 14 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.