COSC 182

JavaLogo Using the javadoc Documentation Tool


Purpose :


Introduction:


Example of javadoc code :

Java code of the Message Class :

/**
 * Class : Message
 *
 * Description : Demonstration class to show the meaning of object class,
 *                properties, methods.
 *               Creats a message object
 *
 *	Date 09/01/2005
 *  DOS command to generate the Documentation using javadoc
 *   C:\jdk1.5.0\bin\javadoc -d javadoc -author  -private Message.java 
 *
 *  @author  JBDR 
 *  @version 1.0 
 */ 
public class Message { /** * Class Property : message */ private String message; //Property /** * Constructor * @param m message String */ public Message(String m) { this.message = m;} /** * Accessor - getMessage() * @return message property */ public String getMessage() { return this.message; } /** * Mutator - setMessage() sets the message property * @param m message to set */ public void setMessage(String m) { this.message = m; } /** * toString() - returns the message property as a string * @return message the property */ public String toString() { return this.message; } /** * main method * Uses the Message class and prints the message on the screen * @param args - array of command line arguments
*/ public static void main(String [] args) { Message test = new Message("Hello World"); //Make an instance of Message called test System.out.println(test.toString()); //Use the accessor method to print the string test.setMessage("New Message"); // Set a new message for the property using mutator System.out.println(test.getMessage()); // Use the accessor method to print the message } }//End Message

HTML Documentation Produced


Instructions for using javadoc

  1. Using javadoc from a DOS window
    1. Open a DOS window
    2. The DOS prompt should show the folder for the files to be documented
    3. Type the DOS command below :

      C:\jdk1.5.0\bin\javadoc -d javadoc -author -version -private Message.java
      1. -d is the directory to put the HTML documents
      2. -author - activates the @author tag
      3. -version - activates the @version tag
      4. -private - documents all methods including private
      5. files to be documented
  2. Creating a batch file (XXXX.bat) to run the javadoc utility.
    1. Create a file called doJavadoc.bat using NotePad in NotePad type the following code :
      C:\jdk1.5.0\bin\javadoc -d javadoc -author -version -private (your file names )
      pause
              
    2. Save the doJavadoc.bat file from NotePad in the directory that your java source files are located.
      To use this file for other documentation copy it to the user folder that you want and edit the file in NotePad.

  3. Using the doJavadoc.bat file
    1. Open the Windows Files Explorer and find the file in the folder that you have your .java code files
    2. Double click on the doJavadoc.bat file.
      .bat files are executable and you can run it by double clicking.
    3. You should see the results of the javadoc run in a DOS window check for errors. If errors occure correct them in your java source code and re-run the batch(.bat) file.
  4. If you are using one of the tools in JCreator :
    1. Select the javadoc tool
    2. Type in the names of the file or files to dcument
    3. The documentation will be generated
  5. Creating a tool in JCreator
    1. Click on the Configure menu option select Options
    2. When the Options dialog box opens double click on the Tools.
    3. When the Tools box opens click the new button. A menu will drop down select Program
    4. Using the file dialog box select the location of the javadoc.exe file. Probably
      C:\jdk1.5\bin\javadoc.exe. The dialog box will close and the Tool javadoc will appear in the Tool list.
    5. Click on the new javadoc Tool and a dialog box will pop up.
      The Command box will have the javadoc file and location selected.
      In the Arguments Box type -d javadoc -author -version -private
      Then using the box button select the File Name option.
      Next in the Initial Directory box , click on the box button and select Current Directory.
    6. On the dialog box press apply and then Ok

      The tool is now ready for use
  6. Defining your own tags
    1. Custom tags can be defined on the javadoc command line.
      a custom Precondition and Postcondition tag is defined by the following command
      c:\jdk1.5.0\bin\javadoc -d Javadoc -author -version -private -tag pre:a:"Precondition:" -tag post:a:"Postcondition:" BankAccount.java
    2. To define a Class tag the following code is required
      -tag class:h:"Class"
    3. To define a Discription tag
      -tag desc:h:"Description"