SECTION 11 Documentation and Help

Tip 86: Document Your Code with Javadoc

The IDE can remind you to add Javadoc comments to classes, and also display warnings to catch errors in your documentation. These Javadoc hints are turned off by default. Open the NetBeans Options window from the Tools window, and select Java Code > Hints. Activate Javadoc hints by checking the boxes in the Javadoc section.

The hints will show up on the left side of the editor as a lightbulb. Let’s say you declare a new class:

With Javadoc hints activated, a lightbulb will now appear next to this line. Mouse over the lightbulb glyph to display the hint: “Create missing Javadoc for MyClass” Executing the hint will generate an empty Javadoc comment for you to fill in:

Let’s say you later add a parameter to the constructor—for instance, public MyClass( int myNumber ). Immediately, the lightbulb will reappear with the hint “Missing @param tag for myNumber”.

Executing this hint will add the annotation @param myNumber to the Javadoc comment:

You can trigger the Javadoc generation action even when hints are deactivated. To add Javadoc to existing classes, place the caret above the declaration, type /**, and press Return. The IDE will generate the Javadoc comment, including appropriate parameters.

In NetBeans IDE 6.1 and later, you can also use code completion within Javadoc comments. Press Ctrl-Space to insert Javadoc annotations and their arguments.

http://javadoc.netbeans.org/

http://www.netbeans.org/issues/show_bug.cgi?id=89603

http://www.netbeans.org/issues/show_bug.cgi?id=111463

At any time during development of a standard Java application, you can auto-generate detailed project documentation from Javadoc comments.

Right-click the project, and select Generate Javadoc from the context menu. Wait for the IDE to generate the HTML files and open them in the web browser. The generated documentation will be stored in your project’s dist/javadoc/ directory ready for browsing and distribution.

To configure Javadoc generation, right-click the project and select Properties. In Build Properties, select Documenting. Here you can enter custom Javadoc options and configure what elements to generate and which additional parameter tags to include.

If the Generate Javadoc command is disabled in the menu, it means your Ant script does not provide a javadoc target. This can be the case in free-form projects which rely on custom Ant scripts. In this case, you need to configure Javadoc generation for your free-form project.

1. First create a custom Ant target for generating Javadoc documentation. (See also the Automate Tasks with Ant section.)

2. In the Projects window, right-click the project and open the Properties window.

3. In the Build and Run Properties panel, map your custom javadoc target to the Generate Javadoc action. Click OK.

The Generate Javadoc menu item is now enabled for your free-form project.

To view class members and their Javadoc in context, open the class in the editor and select Navigate > Inspect > Members from the menu.

NetBeans platform development becomes a lot easier when you integrate the API Javadoc into the IDE. The Platform Javadoc contains a lot of useful information—for example, which entries you can use in the layer.xml file.

This is how you install the NetBeans API Javadoc in the IDE.

1. In the IDE, choose Tools > Plugins from the menu and go to the Available Plugins Tab.

2. Select NetBeans API Documentation and click Install.

3. Open your web browser and download the NetBeans Platform 6.0 sources from http://download.netbeans.org/netbeans/6.0/final/zip.

4. In the IDE, choose Tools > NetBeans Platform Manager from the menu.

5. Go to the Sources tab and click Add Zip/Folder. Browse to the IDE sources Zip file to add it to the Platform Manager. Click Close.

When developing an application based on the NetBeans platform, you can now read the original sources and you can refer to the Platform API Javadoc. Try it: Ctrl-Click an identifier, and you jump directly to the actual source code where the item was defined.