CS596: Doc 11, Javadoc

	CS 596 Java Programming Fall Semester, 1998 Javadoc
	To Lecture Notes Index © 1998, All Rights Reserved, SDSU & Roger Whitney San Diego State University -- This page last updated 10-Oct-98

Contents of Doc 11, Javadoc

Reference

The Java Programming Language 2 ^nd Ed., Arnold, Gosling, 1998, Chapter 11

Online Javadoc reference at

Javadoc 1.1 http://www.sdsu.edu/doc/jdk1.1/docs/tooldocs/solaris/javadoc.html

Javadoc 1.2 http://www.eli.sdsu.edu/doc/jdk1.2/docs/tooldocs/solaris/javadoc.html


Doc 11, Javadoc Slide # 2

Using Javadoc
There are several steps in creating Java documentation using javadoc. First, there is inserting the proper comments in your source code. Second is running javadoc. If you use javadoc from JDK 1.1 (javadoc 1.1) you will also will want is modifying the output of javadoc to properly find the standard images use in javadoc documentation. This is not needed if you use javadoc from JDK 1.2 (javadoc 1.2).

Javadoc Comments
Comments that start with /** and end with */ that are placed just before methods, constructors, fields, classes, and interfaces are used by javadoc to generate javadoc documentation. The following small example illustrates some javadoc comments. See http://www.sdsu.edu/doc/jdk1.1/docs/tooldocs/solaris/javadoc.html for more details on javadoc comments and the javadoc tags.


S-oct7 8mins, Q-oct8 9mins Doc 11, Javadoc Slide # 3

Sample Program with Javadoc tags

package cs535;
import java.io.IOException;
/**
 * This is a javadoc comment for the entire class. Below I
 * use some special tags.
 *
 * @version 0.1 28 November 1997 
 * @author Roger Whitney 
* (<a href=mailto:whitney@cs.sdsu.edu>
 whitney@cs.sdsu.edu</a>)
 * @see java.io.Writer
 * @see java.util.Vector
 */
public class SampleClass {
   /**
    * This is a javadoc comment for a field.
    */
   private int myField;
   /**
      This is a javadoc comment for a method. Note that
      I don’t need to use the line of *'s at the left.
     @param right Describe right here.
     @param left Describe left here.
     @exception IOException Talk about the exception here.
     @return a float value is returned
    */
   public float test( int  left, int right ) throws IOException {
      return 5.0f;
   }
}
S-oct7 2mins, Q-oct8 5mins Doc 11, Javadoc Slide # 4

Running Javadoc
See http://www.sdsu.edu/doc/jdk1.1/docs/tooldocs/solaris/javadoc.html for the “official” documentation on javadoc with all the flag options. The most common mistake beginners make it javadoc is not making their classes public. Javadoc does not produce documentation for non-public classes. Another common mistake is not using the proper flags to display all the javadoc tags in your classes. Not all tags are displayed by default. The general format of the javadoc command line is:

javadoc [options] packages or files to process

For example I put the above program in a file SampleClass.java in the directory /net/www/www-eli/java/cs535. I then moved to the directory /net/www/www-eli/java. I then ran the following command:

javadoc -version -author -d myDocs cs535

The -version -author flags tell javadoc to show the version and author tags. The -d myDocs flag tells javadoc to place the html documentation in the directory myDocs. This directory must exist before you run the command. The path cs535 tells javadoc to process all .java files in the subdirectory cs535. You can give relative or absolute path name. You can also give a path to the top level of a package to have javadoc generate documentation for all classes in a package. The contents of myDocs is now:

AllNames.html cs535.SampleClass.html tree.html
Package-cs535.html packages.html

The following command done in the directory /net/www/www-eli/java/cs535 (which contains the file SampleClass.java) will generate the javadoc documentation for all files ending in .java in the current directory.

javadoc *.java


S-oct7 2mins, Q-oct8 2mins Doc 11, Javadoc Slide # 5

Modifying Javadoc 1.1 output
Javadoc 1.1 has one irritating feature: it assumes that all images used in the javadoc html documentation are in a subdirectory of the directory containing the javadoc documentation. When you view this documentation with a web browser you will see boxes there the images for methods, constructors, fields, etc, should be located. There are two ways to correct this. The first one is to copy the directory of images to the directory containing your javadoc documentation. The second way is to use class sdsu.doc.FixJavadoc, which is part of the SDSU Java library.

java sdsu.doc.FixJavadoc

If the SDSU java library is in your path and you execute the above line in the directory containing all your javadoc documentation it will correct all references to the images in all files ending in .html.


S-oct7 2mins, Q-oct8 7mins Doc 11, Javadoc Slide # 6

Javadoc 1.2 Javadoc 1.2 has been changed from javadoc 1.1. A few more tags were added. Javadoc 1.2 uses tables and style sheets, but no images.

The following example assumes:
1 that the file SampleClass.java (see slide 3) is in the directory /net/www/www-eli/java/cs535.

2 the directory /net/www/www-eli/java/cs535 is in your class path

3 your path is set to use JDK1.2

4 the file package.html is in the directory /net/www/www-eli/java/cs535 with the following contents.

package.html

<BODY>
This is a sample package. This is a second
<B>sentence</B>.
@see cs535.SampleClass
</BODY>

The package.html file is used for package level comments. You place your text, which can contain html tags, between the <BODY> - </BODY> tags. Text outside the <BODY> - </BODY> tags is ignored.

To generate the documentation for the cs535 package use the following command:

javadoc -version -author -d myDocs cs535

Note, do not give javadoc1.2 the name of a package (cs535) in the directory containing the cs535 package (/net/www/www-eli/java/cs535) or the directory containing the cs535 directory (directory /net/www/www-eli/java). In those directories give the actual file names that you want processed. The -version flag tells javadoc to include version tags. The -author flag tells javadoc to include author tags. The -d myDocs flag tells javadoc to place the documentation in the directory myDocs relative to the current directory. The cs535 argument tells javadoc which package to process. You can list more than one package. You can also list files names. See http://www.eli.sdsu.edu/doc/jdk1.2/docs/tooldocs/solaris/javadoc.html for more information about javadoc 1.2 options. See http://www.eli.sdsu.edu/doc/jdk1.2/docs/tooldocs/javadoc/whatsnew.html for an overview of the differences between javadoc 1.1 and javadoc 1.2

visitors since 05-Oct-98