4.6. Writing Javadoc Comments

So far, we have seen how to generate an API Documentation website using existing Javadoc comments. However, we still need to add some comments to the code to fix those warning messages we received when creating the website. This section will focus on enabling you to write your own comments in the code.

Take a moment to navigate back to your API Documentation website in your browser. When you first visit the website, you will see a link to the Circle class on the left and under the Class Summary.

Note

If there were multiple classes within this package, the website would display all of the classes in the package. To see the documentation for the Circle class, click on either of the links.

Exploring the Existing Code / Website

  1. Open Circle.java in your terminal. Compare the Javadoc comments for the Circle class to what you see on the website. Notice how the text is rendered differently in your browser based on the tags that were used in the comments. Look closely at the effect of @code vs. @link.

  2. With Circle.java still open in your terminal, compare the Javadoc comments for the Circle constructor to what you see under the Constructor Summary on the website. The Javadoc tool was able to correctly determine that this method is a constructor based on the fact that it has the same name as the class and is lacking a return type.

  3. Take note of any Javadoc tags in the constructor comments that weren’t present in the comments for the class. Our constructor takes in a parameter which is described using the @param tag. Immediately after the @param tag is the name of the parameter followed by a description. The @throws tag works similarly for any exceptions that are propagated by the method.

  4. Notice that neither the @param nor the @throws descriptions are listed in the Method Summary section of the website. To see those comments, you can either click on the constructor name in the Constructors list or scroll down to the Constructor Detail section of the web page.

Finishing the Javadoc Comments

  1. Under the Method Summary section of the website, you will notice that only some of the methods contain Javadoc comments. This is why we received warning messages when we ran the javadoc command to create the website earlier. We intentionally left out the comments for the setRadius, getDiameter and getArea methods to allow you to write your own Javadoc comments.

  2. Before adding comments to Circle.java, take a moment to look at the Method Detail section of the website. Compare a documented method (getRadius or getPerimeter) to an undocumented method.

  3. In Circle.java, add Javadoc comments for each undocumented method using the others as a template. In each of your comments, include a sentence that describes the method, along with tags that document the parameters, return type, and propagated exceptions where needed. Use the @code tag where appropriate in your description.

Updating the Website

  1. Make sure you are in cs1302-javadoc. Use the same command presented earlier to regenerate the API documentation website for the code contained in this tutorial:

    javadoc -d doc -sourcepath src -subpackages cs1302

    Executing this command will update the files in the doc directory.

  2. You do not need to create the symbolic link again using ``ln``!

    Remember, we created a symbolic link in public_html that targets the doc folder. This link still exists and we didn’t move doc - we simply updated the files within doc. Therefore, we don’t have to take any additional steps to update the website — they are now visible by refreshing the page in your web browser.

    Since the symbolic link points to your doc folder, it will automatically point to the newly generated content.

  3. If you haven’t done so already, go look (refresh your browser page)!