Roumen's Weblog

Javadoc Support in NetBeans

I've found out that a lot of people come to my blog by searching "javadoc NetBeans" keywords in Google. Interesting, isn't it? It seems to me that there is a demand for more information on javadoc support in NetBeans. Since javadoc-related features are kind of tricky, I've decided to write a post about it, maybe it will help somebody with solving problems with it.

There are several levels of support of javadoc in NetBeans:

• 1. Javadoc in code completion
• 2. Javadoc generating for a project
• 3. Displaying Javadoc from the IDE
• 4. Javadoc index search
• 5. Javadoc in navigator
• 6. Autocomment tool

I'll go through these topics and try to cover the most common pitfalls.

1. Javadoc in code completion

Code completion has a javadoc window which displays javadoc for currently chosen java element (method, field, etc.). The javadoc window is enabled by default - this can be toggled in Tools | Options | Editing | Editor Settings | Java Editor | Auto Popup Javadoc Window.

The JDK javadoc is taken from one of these sources:

• java source files
• generated html javadoc

The situation is simple with JDK 1.4 or newer because the JDK contains a src.zip file which contains all the sources (except for some security-related classes). So you don't have to do anything, the javadoc window displays the javadoc for you.

The situation is complicated on MacOSX where JDK doesn't contain the src.zip file - in this case you need to download the whole javadoc from:

http://java.sun.com/docs/index.html

This javadoc should be saved on your disc, preferably in the "docs" subdir of your active JDK. Then you need to go to Tools | Java Platform Manager, choose the Javadoc tab, press the "Add ZIP/Folder" button and point it to the docs directory. Now javadoc on Mac will work for you in code completion's javadoc window.

Javadoc for classes in project works out of box, it is just parsed from the sources you write, so there's no additional effort necessary.

Javadoc for project libraries needs to be configured in Tools | Library Manager. Choose the library for which you want javadoc to be displayed and similarly to older JDK go to Javadoc tab and point it to the javadoc directory of your library.

Warning: You need to point the dialog to the correct directory - it needs to contain usual javadoc files - index.html, overview-tree.html, and so on and subdirectories index-files, resources, etc. The dialog will not tell you when you will choose an incorrect directory or a broken javadoc directory. We need to fix this in the future, but this is how it works at the moment.

2. Javadoc generating for a project

To generate javadoc for your project, use Build | Generate Javadoc. You can also use the project context menu (available on right-click). To set up parameters for javadoc, go to project properties in context menu and choose Build | Documenting section. Here you can configure the usual parameters of javadoc.

3. Displaying Javadoc from the IDE

At first, make sure you have your browser configured correctly in Tools | Options | IDE Configuration | System | System Settings. You need to set the correct browser and proxy settings if necessary. When set up, go to View | Documentation Indices and choose the javadoc you want to display. You will see there javadoc for the libraries you've set up. JDK javadoc can be shown using context menu on JDK libraries (Show javadoc). See paragraph below which explains how to add javadoc of your current project into this submenu.

You can also show javadoc for a java element (method, class, field, etc.) by pressing Alt-F1 on that element.

4. Javadoc index search

To make Tools | Javadoc index search work you need to configure the Javadoc tab in platform manager or library manager - depending if you want to show JDK or project library javadoc. The situation is more complicated with javadoc for classes from your project. If you generate javadoc for your project, it is created in dist/javadoc subdirectory in your project dir. Now you want to let the IDE know that it should search this javadoc as well. The way I've found for this is to add an artificial library to your project through Library manager. This library must contain jar with your project (needs to be there, otherwise the javadoc won't be shown) and it must contain the javadoc for your project. When this is set up you can search javadoc for your project as well. This obviously is not very well designed and we should improve it in next releases.

Update: Second workaround to make javadoc search and documentation indices work for project classes is to restart the IDE. Much simplier than first workaround. Still deserves to be improved.

5. Javadoc in navigator

Navigator displays javadoc for individual elements on mouseover. The javadoc is taken from sources and it works out of box, no extra configuration is necessary.

6. Autocomment tool

Autocomment tool enables you to add easily javadoc comments to your source. It's located in Tools | Auto Comment. It shows you all cases where javadocs are missing and you can fill them in. It also helps you with solving the javadoc warnings. The name of this tool is a bit misleading, because it won't fill in the comments for you, you still have to type them in.

I hope this covers all important topics for javadoc support in NetBeans. My opinion is that the javadoc support is good - it works and provides all necessary functionality, but we need to make it's configuration easier. This seems like work for our usability team.