Here we briefly look at the javadoc tool provided with the SDK for automatically creating hypertext pages describing your classes and packages.

We noted in Chapter 2: Java : Comments that Java recognizes comments three ways. Double forwared slashes // will denote a single line comment. A block of comments can be bracketed with /*...*/.

The third approach is basically the same as the latter, but with an extra asterisk. The javadoc automatic hypertext documentation will recognize such comments and use them in the documents.

For example, here is a HelloWorld.java file commented in the javadoc style.

 

Note that the /** ...*/ comments should be placed immediately before the class, method, and variable they are describing. (The intermediate astericks are ignored so they are used in the above comments to give a neat left edge to each comment.)

The following shows the results of processing this file with javadoc :

C:\Java\Courses\CourseWork\tmp>javadoc HelloWorld.java Loading source file HelloWorld.java... Constructing Javadoc information... Building tree for all the packages and classes... Building index for all the packages and classes... Generating overview-tree.html... Generating index-all.html... Generating deprecated-list.html... Building index for all classes... Generating allclasses-frame.html... Generating index.html... Generating packages.html... Generating HelloWorld.html... Generating serialized-form.html... Generating package-list... Generating help-doc.html... Generating stylesheet.css... ;

This creates several hypertext documentation files such as HelloWorld.html whose contents are shown below :

Class  Tree  Deprecated  Index  Help
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD	DETAIL:  FIELD | CONSTR | METHOD

---

Class HelloWorld

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--java.awt.Panel
                    |
                    +--java.applet.Applet
                          |
                          +--HelloWorld

---

public class HelloWorld

extends java.applet.Applet

This applet tests graphics. (This comment must be placed immediately before class line.)

See Also:

Serialized Form

---

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

 

Constructor Summary

HelloWorld()

 

Method Summary
void	paint(java.awt.Graphics g)           This method paints the text to the screen.

 

Methods inherited from class java.applet.Applet

destroy, getAppletContext, getAppletInfo, getAudioClip, getAudioClip, getCodeBase, getDocumentBase, getImage, getImage, getLocale, getParameter, getParameterInfo, init, isActive, newAudioClip, play, play, resize, resize, setStub, showStatus, start, stop

 

Methods inherited from class java.awt.Panel

addNotify

 

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getInsets, getLayout, getMaximumSize, getMinimumSize, getPreferredSize, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paintComponents, paramString, preferredSize, print, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, removeNotify, setFont, setLayout, update, validate, validateTree

 

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addPropertyChangeListener, addPropertyChangeListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, getBackground, getBounds, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getGraphics, getHeight, getInputContext, getInputMethodRequests, getLocation, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isDisplayable, isDoubleBuffered, isEnabled, isFocusTraversable, isLightweight, isOpaque, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, remove, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, reshape, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setForeground, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, show, show, size, toString, transferFocus

 

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

 

Constructor Detail

HelloWorld

public HelloWorld()

Method Detail

paint

public void paint(java.awt.Graphics g)

This method paints the text to the screen. (This comment must be placed immediately before method line.)

Overrides:

paint in class java.awt.Container

---

Class  Tree  Deprecated  Index  Help
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD	DETAIL:  FIELD | CONSTR | METHOD

---

You may recognize this style of output as the same as used in the Java API Specifications.

Note that you can use hypertext tags in the javadoc comments, such as <br> for line breaks and list tags such as <ul> <li>abc</li></ul>. For more elaborate modifications to the standard javadoc output, see the doclets and taglets documentation.

References & Web Resources

• Javadoc 1.4.2 - SDK Tools
• javadoc Reference - Windows
• javadoc Reference - Solaris