ch33.htm

Java_by_Example,初级经典例子哦,珍藏版本

</BLOCKQUOTE>

<HR>

<H3><A NAME="RunningtheDebuggerfromAppletviewer">

Running the Debugger from Appletviewer</A></H3>

<P>

In addition to being able to run several applets at once, Appletviewer

can also start a debugging session with an applet. In fact, running

the Java debugger, jdb, is the only parameter, besides the name

of the HTML document, you can use with Appletviewer. To run an

applet with the debugger, you would type a command like this:

<BLOCKQUOTE>

<PRE>

appletviewer -debug applet.html

</PRE>

</BLOCKQUOTE>

<P>

For more information about Java's debugger, refer to the section

&quot;Using the Debugger&quot; later in this chapter.

<H2><A NAME="UsingHotJava"><FONT SIZE=5 COLOR=#Ff0000>

Using HotJava</FONT></A></H2>

<P>

HotJava is a complete Web browser that was written using the Java

language. Although it's a good example of how much mileage you

can get out of the Java language, it hasn't been kept up to date.

In fact, even though HotJava was the first Java-compatible browser,

it can no longer load and run most current applets. This is because,

as the Java language progressed from its beta versions to the

version 1.0 release, the HotJava browser was not kept up to date.

As a result, HotJava can load and run only applets that were created

using the old version of Java. A set of these applets come with

HotJava so that you can check them out. Figure 33.2, for example,

shows HotJava running the Hang Duke applet.

<P>

<A HREF="f33-2.gif"><B> Figure 33.2 : </B><I>HotJava can only run applets that were created with the early beta version of Java.



</I></A><P>

<P>

Although you can still use HotJava to browse the World Wide Web,

you're probably better off getting a copy of Netscape Navigator

2.0, which is available for download at <TT><A TARGET="resource window" HREF="http://www.netscape.com">http://www.netscape.com</A></TT>.

Netscape Navigator 2.0 not only is a much more powerful Web browser,

it can also load and run applets created with the latest version

of Java. (It cannot, however, load the older applets, which are

considered to be obsolete at this point.) Figure 33.3 shows Netscape

Navigator 2.0 running the Fractal sample applet.

<P>

<A HREF="f33-3.gif"><B> Figure 33.3 : </B><I>Currently, Netscape Navigator 2.0 is the Java-compatible Web browser to use.



</I></A><P>

<H2><A NAME="UsingJavasDocumentationcreator"><FONT SIZE=5 COLOR=#Ff0000>

Using Java's Documentation Creator</FONT></A></H2>

<P>

The javadoc tool won't help you write better Java source code,

but it'll sure go a long way towards helping other people use

your code, not to mention help you remember six months from now

what your code is doing. Basically, javadoc reads through your

source-code files and creates HTML files that document your packages

and classes, including methods and data fields. You can run javadoc

on any old source code, but it works better if you document your

code properly as you work.

<P>

For example, if you want javadoc to include descriptions of your

methods in the HTML files it creates, you need to include a doc-comment

block before each method. A doc-comment block begins with the

characters <TT>/**</TT> and ends like a normal C comment. Listing

33.2 is an example of a simple doc-comment block:

<HR>

<BLOCKQUOTE>

<B>Listing 33.2&nbsp;&nbsp;LST33_2.TXT: A Simple Doc-Comment Block.

<BR>

</B>

</BLOCKQUOTE>

<BLOCKQUOTE>

<PRE>

/**

 * Creates the applet's textfield controls and adds

 * the controls to the applet's display,

 */

</PRE>

</BLOCKQUOTE>

<HR>

<P>

When javadoc sees this comment block beginning with the characters

<TT>/**</TT>, it'll know to include the text of the comment in

the method's description.

<H3><A NAME="JavadocTags">

Javadoc Tags</A></H3>

<P>

In order to simplify the documentation process even more, javadoc

can understand special symbols called doc tags. Doc tags begin

with the <TT>@</TT> symbol. After the <TT>@</TT> are the words

<TT>see</TT>, <TT>version</TT>, <TT>param</TT>, <TT>return</TT>,

<TT>exception</TT>, or <TT>author</TT> followed by the text associated

with the symbol. The doc tag

<BLOCKQUOTE>

<PRE>

@author Jeremy Bender

</PRE>

</BLOCKQUOTE>

<P>

for example, creates an author entry in the class documentation

files, whereas the doc tag

<BLOCKQUOTE>

<PRE>

@version 1.0

</PRE>

</BLOCKQUOTE>

<P>

adds a version entry to the class documentation.

<P>

Use the <TT>@param</TT> tag to decribe a method's parameters,

like this:

<BLOCKQUOTE>

<PRE>

@param paramName Description

</PRE>

</BLOCKQUOTE>

<P>

Here, <TT>paramName</TT> is the parameter's name and <TT>Description</TT>

is the text you want displayed as the parameter's description.

The other tags are used like this:

<BLOCKQUOTE>

<PRE>

@return Description

@exception exceptionName Description

</PRE>

</BLOCKQUOTE>

<P>

The first line above describes the return value of the method,

whereas the second line describes the exception that may be thrown

by the method.

<H3><A NAME="ExampleUsingDocTags">

Example: Using Doc Tags</A></H3>

<P>

One of the most useful doc tags is <TT>@see</TT>, which enables

you to create &quot;See Also&quot; hyperlinks in the HTML documents

created by javac. By using <TT>@see</TT> tags in a method's doc-comment

block, for example, you can add a convenient link in the documentation

that can jump the user straight to a related method with a single

mouse click. If you have complementary methods called <TT>GetString()</TT>

and <TT>PutString()</TT>, for example, you might have a doc-comment

block like the one shown in Listing 33.3.

<HR>

<BLOCKQUOTE>

<B>Listing 33.3&nbsp;&nbsp;LST33_3.TXT: Creating Hypertext Links

in Doc-Comment Blocks.<BR>

</B>

</BLOCKQUOTE>

<BLOCKQUOTE>

<PRE>

/**

 * Retrieves a test string from the user.

 *

 * @param userNum The user's ID number

 * @return The string the user entered

 * @see #PutString()

 */

</PRE>

</BLOCKQUOTE>

<HR>

<H3><A NAME="ExampleDocumentinganApplet">

Example: Documenting an Applet</A></H3>

<P>

To give you a real-world example of documenting a class with javadoc,

you'll now examine an applet from an earlier chapter in this book

with doc-comment blocks added. Listing 33.4 shows the newly documented

applet. To create the HTML documents for the class, copy the ArcApplet.java

file to your CLASSES folder and type <TT>javadoc arcapplet.java</TT>

to start the documentation process. After javadoc finishes, you'll

have four new HTML files in your CLASSES folder: ARCAPPLET.htmL

(Figure 33.4), ALLNAMES.htmL (Figure 33.5), TREE.htmL (Figure

33.6), and PACKAGES.htmL (which, in this case, contains nothing

of value).

<P>

<A HREF="f33-4.gif"><B> Figure 33.4 : </B><I>This is the ARCAPPLET.htmL file viewed in Netscape Navigator.



</I></A><P>

<P>

<A HREF="f33-5.gif"><B> Figure 33.5 : </B><I>This is ALLNAMES.htmL viewed in Netscape Navigator.



</I></A><P>

<P>

<A HREF="f33-6.gif"><B> Figure 33.6 : </B><I>This is TREE.htmL viewed in Netscape Navigator.



</I></A><P>

<HR>

<BLOCKQUOTE>

<B>Listing 33.4&nbsp;&nbsp;ArcApplet.java: An Applet Prepared

for Javadoc.<BR>

</B>

</BLOCKQUOTE>

<BLOCKQUOTE>

<PRE>

import java.awt.*;

import java.applet.*;



/**

 * ArcApplet demonstrates drawing arcs by enabling the user

 * to input the arc's parameters.

 *

 * @version 1.0, 1/15/96

 * @author Clayton Walnum

 */

public class ArcApplet extends Applet

{

    TextField textField1, textField2;



    /**

     * Creates the applet's textfield controls and adds

     * the controls to the applet's display.

     *

     * @return None

     */

    public void init()

    {

        textField1 = new TextField(10);

        textField2 = new TextField(10);



        add(textField1);

        add(textField2);



        textField1.setText(&quot;0&quot;);

        textField2.setText(&quot;360&quot;);

    }



    /**

     * Retrieves the user-defined parameters from the text

     * boxes, converts them to integers, and uses them

     * to display an arc.

     *

     * @return None

     * @param g The applet's Graphics object

     * @see #action

     */

    public void paint(Graphics g)

    {

        String s = textField1.getText();

        int start = Integer.parseInt(s);



        s = textField2.getText();

        int sweep = Integer.parseInt(s);



        g.drawArc(35, 50, 125, 180, start, sweep);

    }



    /**

     * Responds when the user presses Enter from one of the

     * applet's text boxes. Calls repaint() to force the applet

     * to redraw its display with the new parameters.

     *

     * @return A boolean value indicating whether the

     *         event was handled.

     * @param event The action's event object

     * @param arg Event-dependent information

     */

    public boolean action(Event event, Object arg)

    {

        repaint();

        return true;

    }

}

</PRE>

</BLOCKQUOTE>

<HR>

<H3><A NAME="JavadocOptions">

Javadoc Options</A></H3>

<P>

When you run javadoc, you can specify where your source-code files

are located, where the generated HTML files should be stored,

and how much information javadoc displays as it runs. The parameters

associated with these options are <TT>-classpath</TT>, <TT>-d</TT>,

and <TT>-verbose</TT>, respectively. Here's an example of using