Using NetBeans to document code. The NetBeans IDE can be used to help generate Javadoc documentation and to check that the documentation is complete.

Transcription

1 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.

2 From the Tools menu select Auto Comment.

3 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 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.

4 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 tag. Similarly when a method returns a value this should be documented with tag. These can be automatically generated.

5 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. tags are automatically generated and appear in the tags window. To complete the documentation entries must be made for both of the tags. Above 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.

6 In the screen shot below 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.

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