Java API and Javadoc - Multimedia Introduction to Programming Using Java - page 486

first entry in the Method summary is for function abs , and we see that it has
attribute static , that it produces a double value, and that it has a double param-
eter (named a ). We also see that it returns the absolute value of a double value:

There is a second function with the same name, which returns a float value.
Click on the underlined word abs , which is a link to another part of the same
web page. The main pane changes to display a more extensive description of the
method, as shown in Fig. II.3. This description even tells you what “absolute
value” means.

What else can you do?
We have shown you the basic ideas of looking at specifications of classes
and methods. There are a few other things you can do using the icons at the top
of the web page. For example, clicking Index will bring up a page that contains
an alphabetical listing of all the packages, classes, interfaces, methods, and fields
in the API packages.
Also, if you do not like frames, click the NO FRAMES link.
Experiment with all the different features, in order to get a good idea what
is available in the Java API specifications. Get used to using this tool regularly,
whenever you need help with some predefined Java class.

II.2 Javadoc

You can extract specifications from your program if you annotate the program
appropriately. This requires placing Javadoc comments —comments of the form:

/** ... */
in appropriate places. The first sentence of the comment (everything up to and
including the first period “ . ”) is used in the summary portions of the Javadoc
documentation. The whole comment (without the comment delimiters) appears
in the detailed portions of the Javadoc documentation.
Since Javadoc documentation is meant mainly for users of classes, Javadoc
generally extracts specifications only for public classes, methods, and fields, —
those that the user can use. Therefore, such public entities are the prime targets
for Javadoc comments. However, it is possible to set a switch that forces Javadoc
to extract comments from private entities as well.
We now discuss briefly the placement of Javadoc comments.