4. Javadoc Lesson

API Documentation with Javadoc

API Documentation with Javadoc

Note

To show the solution for this activity, you will need to toggle “Show Solutions” above.

Lesson Objectives

This lesson is designed to get you acquainted with Javadoc comments. In particular, it walks you through the transformation of non-Javadoc comments at the class-level and method-level into Javadoc comments so that the Javadoc program can be used to generate a documentation website. In addition to the generated website, the comments themselves also help programmers who are reading your code. Proper comments save companies and teams real world money by lowering transaction costs associated with interpreting code.

Prerequisites

Course-Specific Learning Outcomes

  • LO2.b: (Partial) Define, throw, and propagate exceptions appropriately in a software solution.

  • LO3.b: Create class, interface, method, and inline documentation that satisfies a set of requirements.

  • LO3.c: Generate user-facing API documentation for a software solution.

Part 1: Creating a Documentation Website (Instructor Demo)

  1. Execute the command below to download and extract the files:

    sh -c "$(curl -fsSl https://cs1302uga.github.io/cs1302-book/_bundle/cs1302-javadoc-lesson.sh)"

    - downloading cs1302-javadoc-lesson bundle...
- verifying integrity of downloaded files using sha256sum...
- extracting downloaded archive...
- removing intermediate files...
subdirectory cs1302-javadoc-lesson successfully created

    Change to the cs1302-javadoc-lesson directory that was created using and look at the files that were bundled as part of the starter code using tree. You should see output similar to the following:

    Listing 13 Directory structure of starter code
    .
└── src
    └── cs1302
        └── doc
            └── House.java

  2. Make sure you are still in the cs1302-javadoc-lesson directory. Write the command to generate the API documentation website for the code contained in this exercise and place it in a subdirectory named doc. Be sure to write the full command in your notes, specifying the -d, -sourcepath, and -subpackages options. In your notes, briefly explain what each of these options mean.

    Note

    Don’t worry about any warnings you see at this time. We will fix those warnings by adding Javadoc comments later in the lesson.

    Solution
    javadoc -d doc -sourcepath src -subpackages cs1302

    Understanding the command: Section 4.3.

  3. Verify that files were generated and placed in the doc directory before continuing.

  4. Make sure you are still in the cs1302-javadoc-lesson directory. Use ln to create a symbolic link (shortcut) named cs1302-javadoc-lesson-doc in your public_html directory. The symbolic link should link to the doc subdirectory containing the API documentation website created in a previous step. Write the exact command used in your notes.

    NOTE: Remember, if you use $(pwd) as described in the reading, then that expression will expand to the absolute path of your present working directory. That is, the string that it expands to will differ depending on where you currently are.

    Solution

    There are two correct commands as discussed in Section 4.4.

    You can use the shortcut command as seen below OR you can use the full absolute path to the doc directory instead of $(pwd)/doc.

    Listing 14 Must be run from directly within cs1302-javadoc-lesson
    ln -s $(pwd)/doc ~/public_html/cs1302-javadoc-lesson-doc

  5. The symbolic link created in the last step is called cs1302-javadoc-lesson-doc. You can see it if you change into your public_html directory and perform an ls -l.

    If you made a mistake generating the symbolic link, take a minute to review Section 4.5 for troubleshooting tips.

  6. Navigate to the following URL in your web browser, replacing user with your Odin username (be sure to remember the ~):

    https://webwork.cs.uga.edu/~user/cs1302-javadoc-lesson-doc/

    You should see the API documentation website that you generated. Other than the website you generated while doing the reading, does this website look similar to any other websites that you may have visited?

Part 2: Additional Practice with Javadoc

  1. From the API documentation website created in Part 1, click on one of the links to the House class. In your notes, list the name of each method that appears to contain commented documentation. How many such methods currently containing Javadoc comments are there?

  2. In House.java, some of the methods already have multiline, non-Javadoc comments. Transform the comments into Javadoc using the appropriate syntax. In each Javadoc comment, include one or more properly punctuated sentences that describe the method. You may base these sentences off the existing comments. Be sure to also include tags that document, as needed, the parameters and return type. Leave out any propagated exceptions for now.

    Use the @code tag where appropriate. A general rule is that nouns that refer to code identifiers (e.g., variable names, class names, method names, etc.) should be differentiated using an @code tag. If done correctly, readers of the documentation website will be able to better identify when a general word is being used versus an identifier.

  3. In House.java, the class itself also has multiline, non-Javadoc comments. Transform the comments into Javadoc using the appropriate syntax. Try to preserve the multi-paragraph nature of the existing comment. Use the @code tag where appropriate.

  4. Run the javadoc tool to update your API documentation website on Odin. You should not need to recreate the symbolic link in ~/public_html, assuming it still exists. This is because the symbolic link is pointing to your doc folder. When the doc folder is updated, the link automatically points to this new content.

  5. View the updated API documentation website.

  6. Repeat the previous three steps until you are confident that the API documentation website displays the documentation corresponding to your comments. Once done, write down the direct URL to the API documentation webpage for the House class.

Part 3: Additional Practice with Exceptions

  1. To ensure that a House object cannot have a negative price, modify the constructor and the setPrice method to throw an [IllegalArgumentException](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/IllegalArgumentException.html) with an appropriate detail message when the price parameter is negative.

    • In both places, create and explicitly throw the exception using the throw keyword inside of an appropriate if statement.

    • In the constructor, do not list the exception in the signature using throws.

    • In the setPrice method, do list the exception in the signature using throws.

  2. Is IllegalArgumentException a checked or an unchecked exception? How do you know?

  3. Update your Javadoc comments so that users of the constructor are aware that the constructor may throw an exception under certain circumstances. At a minimum, appropriate use of the @throws tag is needed, regardless of whether the exception is listed using throws in the method signature.

  4. Run the javadoc tool to update your API documentation website on Odin. Find the constructor and setPrice method in the “Construtor Detail” and “Method Detail” sections of the House classes documentation webpage, respectively. How does their documentation _differ_ with respect to the exception? Why?

    Note: In general, when a method throws an unchecked exception, we will not list it in the signature of the method. We did it in this exercise for setPrice only to see the difference in the documentation webpage.

  5. Run the 1302 checkstyle program on House.java. If errors are reported, look up each error message in the [Style Guide](https://github.com/cs1302uga/cs1302-styleguide), fix the error, and repeat until no style errors remain.