Defining Classes II - Absolute Java - page 332

own @param and appear on a separate line. The parameters and their @param
description should be listed in their left-to-right order in the parameter list. If there
are multiple authors, they should each have their own @author and appear on a
separate line. The author and version information is not extracted unless suitable
option flags have been set, as described in the next subsection.
If @deprecated is included in a method comment, then the documentation notes
that the method is deprecated . A deprecated method is one that is being phased out. To
allow for backward compatibility, the method still works, but it should not be used in
new code.
If an @ tag is included for an item, javadoc extracts the explanation for that item
and includes it in the documentation. You should always include a more or less
complete set of @ tags in the comment for each of your methods. In this topic, we omit
the @ tags to save space, but we encourage you to always include them. The comments
that are not part of an @ tag appear as a general comment for the method, along with
the method heading.
You can also insert HTML commands in your comments so that you gain more
control over javadoc , but that is not necessary and may not even be desirable. HTML
commands can clutter the comments, making them harder to read when you look at
the source code.

deprecated

Running javadoc ★
To run javadoc on a package, all you need to do is give the following command:

javadoc -d Documentation_Directory Package_Name
It would be normal to run this command from the directory containing the classes in
the package, but it can be run from any directory, provided you have correctly set the
CLASSPATH environment variable. The Documentation_Directory is the name of the
directory in which you want javadoc to place the HTML documents that it produces.
For example, the following might be used to obtain documentation on the package
mylibraries.numericstuff :

javadoc -d documentation/mypackages mylibraries.numericstuff
The HTML documents produced will be in the subdirectory documentation/
mypackages of where this command is run. If you prefer, you may use a complete path
name in place of the relative path name documentation/mypackages . If you omit the
- d and Documentation_Directory , javadoc will create suitable directories for the
documentation.
You can link to standard Java documents so that your HTML documents include
live links to standard classes and methods. The syntax is as follows:

javadoc -link Link_To_Standard_Docs -d Documentation_Directory
Package_Name