Have you ever wonder how those nice web pages documenting the methods
of a class, such as the one for the
Color class, are generated.
They are done with
Javadoc
which we're going to look at now.
Javadoc is a standard
for providing automatic documentation of the
programs you write. Undoubtedly, you've noticed those
pop-up windows NetBeans displays when it comes time to type
in a method name and its arguments.
This is another use of JavaDoc.
We are going to use an external web browser to view the JavaDocs we
generate, so begin by verifying NetBeans' choice of external browser.
(This should only be necessary on a Linux box without Netscape.) In
the NetBeans Window, select Tools and then
Options. In the pop-up window, scroll until
you find Web Browsers, which is
directly below ServerAndExternalToolSettings.
Underneath
Web Browsers select the first
External Browsers option, this should be
External Browsers (UNIX) on a Linux machine
(External Browsers (Windows) on a Windows box).
Verify that the appropriate browser is designated; on our Linus boxes,
the designation should read: mozilla {params}.
Change the designation if necessary.
While it is not readily apparent why you would want to go through so
much trouble for a small program, when you are working as part of a team
writing thousands of lines of code, standard methods of
documenting your program are crucial.
Right-Click on file. --> Tools --> Auto Comment...
Your Assignment ...
Open the StopLight.java file. Click the
Tools menu, and select Auto
Comment. In the left pane, select the public
static void main() entry. This will pull up the JavaDoc
creation screen for the main() method.
In the JavaDoc Comment Text box, enter the
following:
Creates the StopLight Frames and starts the Control
threads. This method is called when the program is started to load
the other classes.
Now click the
New button. Select the
@param option and click OK. Now for the
Parameter field, click the drop down arrow
way to the right of the field, and select
Args.
For the description field, type:
This gets the command line arguments passed by the user.
Finally, close the Auto Comment screen.
Notice that new comments were inserted into your document just before
the start of the main method. These comments
are in the special JavaDoc format. Many different programs (including
NetBeans) can use this information to make automatic documentation.
For instance, to generate a web page containing information on your
program, click the Tools menu and select
Generate JavaDoc. After a short period,
NetBeans should ask you if you want to view it, click Yes.
