Using NetBeans to document code
The NetBeans IDE can be used to help generate Javadoc documentation and
to check that the documentation is complete.
Before you generate documentation you should set the place where it will be
stored. By default this is in your profile area and you probably don’t want
this! From the main NetBeans window select “Tools” on the top menu bar.
From this menu select “Options”. Now select “Documentation”. A set of
properties will be listed. Set “Ask for Destination Directory” to True.
NetBeans will now prompt you as to where your documentation should be
stored. Close the menu.
To document code, first open it in the source code editor.
From the “Tools” menu select “Auto Comment”.
The following window will appear:
The left hand upper pane of this window contains a number of entries. What
is shown will depend on the selection made on the square buttons at the top
right of the window.
The tool distinguishes between documented and undocumented code. Code is
considered documented only if it has descriptive text associated with it. The
documentation for a method is only considered to be complete if all its
arguments and its return value are described using @param and @return tags.
The green square is used to indicate complete documentation. The yellow
triangle indicates partially complete documentation. The red square indicates
the absence of any documentation.
Selecting the green button will show all the code elements for which the
documentation is complete. Selecting the yellow button will show all the code
elements for which the documentation is partially complete. Selecting the red
button will show all the code elements that have no documentation associated
with them. It is recommended that all three buttons should be selected.
The other four buttons:
are used to select whether public, package level, protected and private items
are shown. The blue open lock shows public items. The yellow square
package displays items visible to the package. The key displays protected
items. The closed grey lock displays private items. Again it is recommended
that all four buttons are selected at all times.
To enter documentation select an item in the top right pane and type the
associated documentation in the right hand panes:
The picture above shows documentation entered for the class. Remember that
Javadoc documentation is actually HTML so it is possible for the
documentation author to embellish their documentation with HTML tags. The
button bar at the bottom right hand of the window can be used to
automatically insert the more popular tags. Sadly, the tool these in upper case
which is of course not according to the XHTML standard.
When a method expects an argument, the argument should be documented
using the @param tag. Similarly when a method returns a value this should be
documented with the @returns tag. These can be automatically generated.
In the screen shot above a method that has an argument and a return type is
selected. In this situation the button labelled “Auto Correct” can be pressed.
The @param and @return tags are automatically generated and appear in the
tags window. To complete the documentation entries must be made for both
of the tags.
Above the @param tag is selected and a description of the parameter is typed
into the description text pane at the bottom right hand corner of the window.
In the screen shot below the @return tag has been selected and the description
for this tag is typed into the same text pane.
All entries made in this tool are automatically added to the source code with
no necessity for pressing “Save” etc.
The documentation is complete when every entry in the top left pane of the
window has a green square next to it. At this point the Auto Comment
window can be closed in the normal way.
The Javadoc can be generated and viewed by selecting “Generate Javadoc”
from the NetBeans “Tools” menu.
When this process is complete the documentation can be viewed in a browser.