SDSU CS 535: Object-Oriented Programming & Design
Fall Semester, 1997
Doc 25, Javadoc

To Lecture Notes Index
San Diego State University -- This page last updated 02-Dec-97

Contents of Doc 25, Javadoc


Online Javadoc reference at

Doc 25, Javadoc Slide # 1
Using Javadoc

There are three steps in creating java documentation using javadoc. First there is inserting the proper comments in your source code. Second is running javadoc. Third is modifying the output of javadoc to properly find the standard images use in javadoc documentation.

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 for more details on javadoc comments and the javadoc tags.

Doc 25, Javadoc Slide # 2
Sample Program with Javadoc tags
package cs535;

 * 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><
 * @see
 * @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;

Doc 25, Javadoc Slide # 3

Running Javadoc

See 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 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:

Doc 25, Javadoc Slide # 4
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 will generate the javadoc documentation for all files ending in .java in the current directory.

javadoc *.java

Modifying Javadoc output

Javadoc 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 the program below. If you run this java program in the directory containing all your javadoc documentation it will correct all references to the images in all files ending in .html. For example I ran the FixJavaDoc program in the directory /net/www/www eli/java/myDocs to correct the javadoc documentation generated by the first javadoc command given above.

Doc 25, Javadoc Slide # 5
import java.util.*;

 * This class fixes a problem with javadoc. Javadoc assumes that
 * all images are in a subdirectory of your current directory.
 * This class reads all files in the current directory that 
 * end in ".html". All references to standard java documentation
 * images in these files are modified to get the images over 
 * the network from
 * @author Peter Proud-Madruga
 * @author Roger Whitney
 * @version 0.8 20 October 1997
class FixJavaDoc
     static final String imageURL = "src=\"";
     static final String imageReference = "src=\"images";
     static Random randomNumber = new Random();
     public static void main( String args[] ) throws Exception
          File currentDirectory = new File( "." );
          String[] listing = currentDirectory.list( new FileExtensionFilter("html"));
          for ( int k = 0; k < listing.length; k++ )
               System.out.println( "Processing file: " + listing[k]);
               correctImageReference( listing[k] );
      * Replaces all occurances of the string imageReference with 
      * the string imageURL in the file "fileName"
     public static void correctImageReference( String fileName)
          File originalFile = new File( fileName );
          File scratchFile =  scratchFile();
          PrintWriter cout = null;
          StringReplaceReader fixed = null;
               BufferedReader bufferedFile = 
                    new BufferedReader( new FileReader( originalFile ) );
               //     StringReplaceReader will replace all occurrances
               // of imageReference with imageURL
               fixed = new StringReplaceReader( 
                              bufferedFile, imageReference, imageURL);
               cout = new PrintWriter
                    ( new BufferedWriter( new FileWriter( scratchFile )));
               // fixed.contents returns file contents after making the 
               // changes
               cout.print( fixed.contents() );
               // can't delete or rename file that has an open stream 
               scratchFile.renameTo( originalFile);
          // only files that exist are opened for reading
          catch (FileNotFoundException shouldNotHappen)
               System.err.println( "FileNotFoundException on existing file");
          catch (IOException ioError )
               System.err.println( "IO error while processing file: " + 
               if (scratchFile.exists() )
      * Return a file which has a name
      * that does not exist in the current directory
     public static File scratchFile()
          String newFileName;
          File newFile;
               newFileName = "" + randomNumber.nextInt();
               newFile = new File( newFileName);
          while ( newFile.exists() );
          return newFile;

visitors since 02-Dec-97