|
|
< Day Day Up > |
|
The javadoc Documentation Tooljavadoc, the Java documentation creator, takes a .java source code file or package name as input and generates detailed documentation in HTML format. For javadoc to create full documentation for a program, a special type of comment statement must be used in the program's source code. Tutorial programs in this book use //, /*, and */ in source code to create comments—information for people who are trying to make sense of the program. Java also has a more structured type of comment that can be read by the javadoc tool. This comment is used to describe program elements such as classes, variables, objects, and methods. It takes the following format: /** A descriptive sentence or paragraph. * @tag1 Description of this tag. * @tag2 Description of this tag. */ A Java documentation comment should be placed immediately above the program element it is documenting and should succinctly explain what the program element is. For example, if the comment precedes a class statement, it will describe the purpose of the class. In addition to the descriptive text, different items can be used to document the program element further. These items, called tags, are preceded by an @ sign and are followed by a space and a descriptive sentence or paragraph. Listing B.3 contains a thoroughly documented version of the AppInfo applet called AppInfo2. The following tags are used in this program:
Listing B.3. The Full Text of AppInfo2.java
1: import java.awt.*;
2:
3: /** This class displays the values of three parameters:
4: * Name, Date and Version.
5: * @author <a href="http://java24hours.com">Rogers Cadenhead</a>
6: * @version 4.0
7: */
8: public class AppInfo2 extends javax.swing.JApplet {
9: /**
10: * @serial The programmer's name.
11: */
12: String name;
13: /**
14: * @serial The current date.
15: */
16: String date;
17: /**
18: * @serial The program's version number.
19: */
20: int version;
21:
22: /**
23: * This method describes the applet for any browsing tool that
24: * requests information from the program.
25: * @return A String describing the applet.
26: */
27: public String getAppletInfo() {
28: String response = "This applet demonstrates the "
29: + "use of the Applet's Info feature.";
30: return response;
31: }
32:
33: /**
34: * This method describes the parameters that the applet can take
35: * for any browsing tool that requests this information.
36: * @return An array of String[] objects for each parameter.
37: */
38: public String[][] getParameterInfo() {
39: String[] p1 = { "Name", "String", "Programmer's name" };
40: String[] p2 = { "Date", "String", "Today's date" };
41: String[] p3 = { "Version", "int", "Version number" };
42: String[][] response = { p1, p2, p3 };
43: return response;
44: }
45:
46: /**
47: * This method is called when the applet is first initialized.
48: */
49: public void init() {
50: name = getParameter("Name");
51: date = getParameter("Date");
52: String versText = getParameter("Version");
53: if (versText != null) {
54: version = Integer.parseInt(versText);
55: }
56: }
57:
58: /**
59: * This method is called when the applet's display window is
60: * being repainted.
61: */
62: public void paint(Graphics screen) {
63: Graphics2D screen2D = (Graphics2D)screen;
64: screen.drawString("Name: " + name, 5, 50);
65: screen.drawString("Date: " + date, 5, 100);
66: screen.drawString("Version: " + version, 5, 150);
67: }
The following command will create HTML documentation from the source code file AppInfo2.java: javadoc -author -version AppInfo2.java The Java documentation tool will create several different web pages in the same folder as AppInfo2.java. These pages will document the program in the same manner as Sun's official documentation for the Java 2 class library.
To see the documentation that javadoc has created for AppInfo2, load the newly created web page index.html on your web browser. Figure B.4 shows this page loaded with Mozilla Firefox. Figure B.4. Java documentation for the AppInfo2 program. The javadoc tool produces extensively hyperlinked web pages. Navigate through the pages to see where the information in your documentation comments and tags shows up. If you're familiar with HTML markup, you can use HTML tags such as A, TT, and B within your documentation comments. Line 5 of the AppInfo2 program uses an A tag to turn the text "Rogers Cadenhead" into a hyperlink to this book's website. The javadoc tool also can be used to document an entire package by specifying the package name as a command-line argument. HTML files will be created for each .java file in the package, along with an HTML file indexing the package. If you would like the Java documentation to be produced in a different folder than the default, use the -d option followed by a space and the folder name. The following command creates Java documentation for AppInfo2 in a folder called C:\JavaDocs\: javadoc -author -version -d C:\JavaDocs\ AppInfo2.java The following list details the other tags you can use in Java documentation comments:
|
|
|
< Day Day Up > |
|