HelloDocumented.java - javadoc-Style Comments

Java Tools Tutorials - Herong's Tutorial Examples

∟HelloDocumented.java - javadoc-Style Comments

This section provides a tutorial example of how to add javadoc-style comments in Java class source code.

If you want to use "javadoc" command to generate an API document for your Java class, you should provide a comment before the class declaration statement and each class member declaration statement using the following syntax:

/**
 * class_method_property_description
 * @tag_name [argument] tag_description
 * @tag_name [argument] tag_description
 * @...
 */

where:

"class_method_field_description" - A short paragraph to describe the class, methor or field.
"@tag_name" - Name of a tag supported by "javadoc" like "@author", "@param", "@return", etc.
"argument" - Argument name to be described in the @param tag.
"tag_description" - A short sentence to describe the item referred by the tag.

Below is a new version my Hello class with javadoc-style comments added.

/**
 * A simple class to demonstrate 'javadoc' comment features.
 * @author Herong Yang
 */
public class HelloDocumented {

  /**
   * Name of the guest.
   */
  public static String guest = "Herong";

  /**
   * The entry point to execute this class.
   * @param a Array of arguments
   */
  public static void main(String[] a) {
    System.out.println("Hello "+guest+"!");
  }
}

Let's see what will be generated by "javadoc" command.

herong$ javadoc HelloDocumented.java

Loading source file HelloDocumented.java...
Constructing Javadoc information...
Standard Doclet version 15+36-1562
Building tree for all the packages and classes...
Generating ./HelloDocumented.html...
Generating ./package-summary.html...
Generating ./package-tree.html...
Generating ./constant-values.html...
Generating ./overview-tree.html...
Generating ./deprecated-list.html...
Building index for all the packages and classes...
Generating ./index-all.html...
Building index for all classes...
Generating ./allclasses-index.html...
Generating ./allpackages-index.html...
Generating ./index.html...
Generating ./help-doc.html...

Open "index.html" in a Web browser, you should see the API document with addition information extracted from those comments in the Java source file.

API Document Generated from javadoc-Style Comments

For more information on "javadoc" tags and usage examples, see "javadoc - The Java API Documentation Generator" at https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html.