CS 535: Object-Oriented Programming & Design

Doc 25, Javadoc Slide # 1

Doc 25, Javadoc Slide # 2

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;
          }
     }

Doc 25, Javadoc Slide # 3

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:

Doc 25, Javadoc Slide # 4

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

javadoc *.java

Doc 25, Javadoc Slide # 5

import java.util.*;
import java.io.*;
import sdsu.io.*;

/**
 * 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 www.eli.sdsu.edu.
 *
 * @author Peter Proud-Madruga
 * @author Roger Whitney
 * @version 0.8 20 October 1997
 */
class FixJavaDoc
     {
     static final String imageURL = "src=\"http://www.eli.sdsu.edu/doc/images";
     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;
          try
               {
               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 
               cout.close();
               fixed.close();
               
               originalFile.delete();
               scratchFile.renameTo( originalFile);
               }
               
          // only files that exist are opened for reading
          catch (FileNotFoundException shouldNotHappen)
               {
               System.err.println( "FileNotFoundException on existing file");
               shouldNotHappen.printStackTrace();
               }
               
          catch (IOException ioError )
               {
               System.err.println( "IO error while processing file: " + 
                         fileName);
               ioError.printStackTrace();
               }
          finally
               {
               if (scratchFile.exists() )
                    {
                    cout.close();
                    scratchFile.delete();
                    }
               }
          }
     
     /**
      * Return a file which has a name
      * that does not exist in the current directory
      */
     public static File scratchFile()
          {
          String newFileName;
          File newFile;
          do
               {
               newFileName = "" + randomNumber.nextInt();
               newFile = new File( newFileName);
               }
          while ( newFile.exists() );
          return newFile;
          }
     }









 visitors since 02-Dec-97