In Java programming, we can use the javadoctool for generating API documentation from comments embedded in source code (Javadoc comments). However, it requires remembering various options of this tool, which is painful and time-consuming. Eclipse IDE can help to relieve this pain by providing the Javadoc Generation wizard. So this tutorial is going to walk you through the steps of generating Javadoc for a Java project using Eclipse. But first, let’s see some sample Javadoc comments:

/**
 * Connects and logins to the FTP server.
 *
 * @throws FTPConnectionException If an I/O error occurs.
 * @throws FTPLoginException If the login operation did not succeed.
 */
public void login() throws FTPConnectionException, FTPLoginException {

	// method body

}

As we can see, the method login() has some comments beginning with /** and ending with */ - which make some Javadocs for the method (Javadoc comments). The generated documentation (in HTML format) for this method would look like the following screenshot:

sample Javadoc for a method

 

Recommended Book: Eclipse IDE: Eclipse IDE based on Eclipse 4.2 and 4.3 (vogella series) (Volume 2)

 

Now, let’s see the steps in details.

In Eclipse IDE, select Generate Javadoc… from Project menu. The Javadoc Generation wizard appears as follows:

Javadoc Generation step 1

In this dialog, do the following steps (as marked by the red numbers in the above screenshot):

  1. Specify location of the javadocprogram on your computer. Typically, it is located under JAVA_HOME’s bin directory. For example, C:\Program Files\Java\jdk1.7.0_21\bin\javadoc.exe, on Windows platform.
  2. Select the project and packages for which you want to generate Javadoc.
  3. Narrow down the source files whose Javadocs will be generated (All files are selected by default).
  4. Limit what class members which will have Javadocs generated, by choosing the visibility (access modifier). For example: If Public is chosen, then only public methods will have Javadocs generated. If Protected is chosen, then only protected and public methods will have Javadocs generated, and so on.
  5. Specify the destination directory where the Javadocs will be put in.
  6. Click Next.

The next screen allows us to specify some arguments and options for the javadoc tool, such as document title (1); document structure (2); documenting tags (3); JAR files and projects to which referenced links are generated (4); and stylesheet for the document (5):

Javadoc Generation step 2

At least you should specify the document title, leave others as default, and then click Next.

In the next screen, we can optionally specify the overview document (1); VM options (2); Extra javadoc options (3):

Javadoc Generation step 3

If you want to reuse the settings for future exports (recommended), check the option “Save the settings of this Javadoc export as an Ant script” (4) and specify the location of the generated Ant build file. This option would be helpful as we tend to generate the Javadocs many times when the project evolves.

If the option “Open generated index file in browser” (5) is checked, then Eclipse will open the generated document in its internal web browser.

Click Finish, it may take a while for Eclipse to execute the javadoc tool to parse the source files and generate all the necessary stuffs, and we end up with a nice documentation as follows (sample):

sample javadoc

 

NOTE: If an Ant build file is generated (when the option “Open generated index file in browser” is checked), then you can execute this Ant file to re-generate the Javadoc without walking through the wizard again. It’s time-saving.

References

 

Recommended Book: Eclipse 4 Application Development: The complete guide to Eclipse 4 RCP development (Volume 1)