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.
Comments:

We mentioned the 'show as tooltips', need to enhance the item 3. Displaying Javadoc from the IDE.

Concerning item 2. Javadoc generating for a project
must to fix the Issue #36470- Add package.html template/wizard
or another one:
Issue 50279- Easy way to make package.html (Javadoc for a source package)
and the new feature:
How to annotate a package in Netbeans?

You really got popular, Today's Page Hits: 2353 WOW!

Posted by pprun on duben 26, 2005 at 05:10 dop. CEST #

Concerning javadoc tooltips, I've added it into internal planning as a proposal. The other javadoc-related issues should be fixed as well (in the long run - the highest priorities first). No, I'm not that popular, only blogs.sun.com didn't flush the daily hits number for 4 days or so :-)

Posted by Roman Strobl on duben 26, 2005 at 06:04 dop. CEST #

Pprun, I've just added 5th item into the summary - javadoc on mouseover in navigator - a bit similar to "show as tooltips" in java sources.

Posted by Roman Strobl on duben 26, 2005 at 06:16 dop. CEST #

I have searched the Internet and read dozens of pages regarding this very issue. Finally I found your page, which seems to be the most easy to understand and comprehensive. However, my problem with NetBeans is still not resolved! All I'm trying to do is load the javadoc for jdk1.5 and apfloat in the IDE!

Note: I am using the downloaded generated html javadoc.

For the jdk1.5 javadoc, I go to Tools|Java Platform Manager|JDK 1.5 (default)|Javadoc| and add the folder "/home/james/programming/Resources/jdk-1_5_0-doc/docs/api" which contains the files and directories you said must be in the javadoc directory.

For the apfloat javadoc, I go to Tools|Library Manager|apfloat|Javadoc| and add the folder "/home/james/programming/sdk/apfloat-1.3/docs" which contains the files and directories you said must be in the javadoc directory.

Then I close and restart the IDE-- with no success. There are no indices listed under View|Documentation Indices| nor does Tools|Javadoc Index Search| work. It gives me an error dialog stating that "Javadoc documentation indices not found".

If you can give me some advice regarding this, I'd sure appreciate it!

Regards,
Yurgen

Posted by Yurgen Wolfgang on prosinec 06, 2005 at 05:56 dop. CET #

Oh boy, do I feel like an idiot! I finally realised that the problem was that I was trying to use NetBeans as just an editor (i.e. avoiding the "project" concept). For some reason that appears to deactivate the javadoc features of the IDE.

Regards,
Yurgen

Posted by Yurgen Wolfgang on prosinec 06, 2005 at 06:21 dop. CET #

I'm glad you made it work :) Yep, you need to be inside the project to make all classpath-related things work.

Posted by Roumen on prosinec 11, 2005 at 03:42 odp. CET #

Ah yeah... regarding this issue, I've encounter the same problem with Roman Strobl and I even try using the old jdk1.4 javadoc, restarting Netbeans, and still cant find any Indices in View -> Document Indices. The difference is I'm using Windoze XP, not in MacOS, and when I try with MacOS X Panther 10.3.9, it works (T_T"), evenwhen I've just downloaded NetBeans(without having the documentation downloaded), and the Javadoc Index Search load in quite a slow speed, as it's surfing the Web. So until now I still either use Navigator, JCreator or use NetBean in MacOS platform to search. Hope to hear experiences from Windoze Netbean users... Regards, Pacman

Posted by Pacman on březen 02, 2006 at 05:35 odp. CET #

Omg... sorry to forget about the HTML syntax... pls help me to add some <br>...

Thanks and regards...

Posted by Pacman on březen 02, 2006 at 05:44 odp. CET #

[Trackback] Arrgh. Took a few hours to realize this: When you add a jar library under the Tools/Library Manager, you can specify a Javadoc directory or zip file. Nothing appears until: a) you add the library to your project b) you RESTART netbeans. Roumen has a...

Posted by Chui's counterpoint on březen 10, 2006 at 03:55 odp. CET #

Thanks a lot for this info! I started to use NetBeans 5.0 for OS X and while everything was really slick, it lacked code completion documentation on standard APIs. I pointed out the jdk-1_5_0-doc.zip without unpacking it. Worked like a charm! Thanks again.

Posted by Tommy on květen 21, 2006 at 04:15 odp. CEST #

Post a Comment:
Comments are closed for this entry.
About

Roman Strobl

Search

Archives
« duben 2014
PoÚtStČtSoNe
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
    
       
Today