Adding Javadoc Comments to Source Files

   

Below your file's tree view in Class Outline is a Javadoc pane. If a class, method, or member variable has Javadoc comments , the comments appear in this pane. When you add a Javadoc comment to your code, IntelliSense displays the first sentence of the comment in the Javadoc pane whenever you highlight a class, method, or member variable name in Class Outline.

The following procedure explains how to add a Javadoc comment to a method; however, you follow the same steps to add Javadoc comments to classes and member variables.

Note   This procedure uses a Console Application project and adds to the code created in the scenario that updates items in Class Outline. If you have not completed the steps that add a Greeting class and hello() method to a basic Console Application, take a few minutes and follow the steps in Adding Items to Class Outline from the Text Editor before continuing.

To add a Javadoc comment to a method

  1. In Project Explorer, click the plus ("+") sign to the left of your project's name to expand your project.

  2. Double-click the filename or icon of the .java file containing your project's main() method (Class1 .java by default).

    Visual J++ opens the Text editor and loads your .java file. The file is now ready for editing.

  3. On the View menu, click Other Windows and select Document Outline from the cascading menu.

    Class Outline appears with a collapsed tree view of your project.

  4. In Class Outline, expand the Greeting class to display the icons for Superclasses, Inherited Members, and the hello() method.

  5. From within the Text editor, type the opening characters for a Javadoc comment, /**, above the hello() method declaration in your source file.

    IntelliSense creates a Javadoc comment block by inserting the closing characters for a Javadoc comment, */, into your code.

  6. After the opening characters of the Javadoc comment block, type the following:
    /** The hello() method is a static method that takes
     * no arguments and returns a String object to the
     * calling method. The value returned will always
     * be "Hello World!".
     */ 
    
  7. In Class Outline, highlight the hello() method.

    Notice that the first sentence of the comment you've just added appears in the Javadoc pane.

When you are creating Javadoc comments for your classes, methods, and member variables, you may want or need to add one or more Javadoc fields to a comment. IntelliSense displays a list of Javadoc fields available in Visual J++. The following procedure adds an author field to the Javadoc comment created above.

To add an Javadoc field to a Javadoc comment

  1. In Project Explorer, click the plus ("+") sign to the left of your project's name to expand your project.

  2. Double-click the filename or icon of the .java file containing your project's main() method (Class1 .java by default).

    Visual J++ opens the Text editor and loads your .java file. The file is now ready for editing.

  3. In the hello() method's Javadoc comment, after the last sentence but before the closing Javadoc characters, */, type an @ sign.

    IntelliSense displays a list box of valid Javadoc comment fields.

  4. Double-click "author" in the list box.

    The word "author" is inserted into your Javadoc comment after the @ sign.

  5. Type your name after @author.

    Your finished Javadoc comment should look like this:

    /** The hello() method is a static method that takes
     * no arguments and returns a String object to the
     * calling method. The value returned will always
     * be "Hello World!".
     * @author Mary Doe
     */