Documenting with JavaDoc

Javadoc is a tool that comes with the JDK that can be used to generate documentation of classes directly from properly commented code. It requires the use of a specific type of commenting that is different from the ones seen in Chapter 1, Getting Started. There, we saw that comments can be added to code using either // or /* or */. JavaDoc uses a specific type of marking to detect what comments were intentionally made for documentation purposes. Javadoc comments are contained within /** and */. A simple example follows.

Example18.java

1  /**

2   * Anonymous class example

3   * This example shows the declaration of an inner class extending

4   * an existing class and overriding a method. It can be used as a

5   * technique to modify an existing method for something more suitable

6   * to our purpose.

7   *

8   * @author Joe Smith

9   * @version 0.1

10  * @since 20190305

11  */

https://packt.live/2J5u4aT

Note

If you are going to generate documentation from a class, you need to make sure the class is public, otherwise, the JavaDoc generator will complain about the fact that it makes no sense to document classes that aren't public.

The new comments include information about the program itself. It is good practice to explain, in some detail, what the program does. Sometimes, it may be convenient to even add blocks of code. In order to support that extra information, there are tags that allow the addition of specific features or metadata to the documentation. @author, @version, and @since are examples of such metadata – they determine who made the code, the version of the code, and when it was first created, respectively. There is a long list of possible tags that you can use; visit https://packt.live/2J2Px4n for more information.

JavaDoc renders the documentation as one or more HTML files. Therefore, it is possible to also add HTML markup to help messages. You could change the documentation part of the previous example as follows:

/**

* <H1>Anonymous class example</H1>

* This example shows the declaration of an <b>inner class</b> extending

* an existing class and overriding a method. It can be used as a

* technique to modify an existing method for something more suitable

* to our purpose.

*

* @author Joe Smith

* @version 0.1

* @since 20190305

*/

Finally, you can create the documentation file by selecting Tools | Generate JavaDoc from the menu:

Figure 3.9: Generating JavaDoc

The JavaDoc generation dialog box will pop up and give you some options. Make sure that you insert the folder where you want the documentation file to be stored (/tmp in the example) and tick the checkboxes for the @author and the @version:

Figure 3.10: Specifying the scope for the JavaDoc

This will generate an HTML file that is formatted in the same way that official Java documentation is:

Figure 3.11: The generated JavaDoc

Activity 2: Adding Documentation to WordTool

Create documentation for the class created in Exercise 1, Creating the WordTool Class.

1. Make sure you document each one of the examples and add enough metadata for people to know how to handle the different methods.
2. Export the resulting documentation file.

   Note

   The solution for this activity can be found on page 536.