WRITING JAVADOC COMMENTS

Javadoc is an industry-wide standard developed by Sun for commenting Java programs, and also a special tool included with the Java SDK which extracts these comments from your Java files to create documentation - these are the pages that you will see when you go to the Java documentation on Sun's website. The comments MUST be set off with the /** ....... */ style of comments to be included by javadoc; other types of comments (both '/*....*/' and '//') are ignored. More information about Javadoc can be found in Savitch, Appendix 4, and also at Sun's Javadoc Home Page.

When you write your programs, you should put comments at the top with the filename of your program, your name, the date last modified, and a brief description (3-5 sentences) telling what the program does. Since the filename doesn't need to be added to the Javadoc description (it takes the name from the class declaration), use '//' comments to put the filename (and any other non-javadoc information) at the beginning of your page for easy identification. You can do this as follows:

 // Student.java

 /**
  * This class will create a student object, identified by name and
  * number, which may be used in simulations; the student will also
  * have an assigned status for class, and arrays to hold courses
  * taken and grades received, indexed in parallel.
  * (You may also include any assertions, assumptions, or other 
  * comments here, including a note to your TF if you've still got any
  * kind of problem with the program.)
  *
  * @author   Jan Jackson
  * @version  Last modified 09_21_01
  **/          

Your name should be designated with the @author tag; if you wish to include the date last modified, do so with the @version tag. Leave a blank line between the end of your description and the '@tags'. NOTE that these tags consist of the '@' symbol - no space after - followed by a specific label, then one or more spaces and the information related to the tag.

METHOD COMMENTS

Each method except main should have its own block of comments just BEFORE the declaration, set off by the /** ......... */ style comment markers. You should include a 1-2 sentence summary of what the method does. For example, suppose I have a method to get two integers. This would be commented as follows:

   /**
    * This method will use two ints declared in the
    * class, and will read in values from the user.
    */
    public static void getNums()
    {
        System.out.print("Please enter the first number: ");
        num1 = SavitchIn.readLineInt();
        System.out.print("Please enter the second number: ");
        num2 = SavitchIn.readLineInt();
    }

If your method passes any parameters, or returns a value, you will need to also include the javadoc tags for parameters or return values. NOTE that you must insert a blank line before the "@tags", and then list and describe them. DO NOT list local variables in these tags, only values which are included in the argument list or are returned. Return tags do not need the variable name. When we cover exceptions, they are also listed with an @exception tag IF THEY ARE THROWN AND NOT HANDLED (CAUGHT) IN THE CURRENT METHOD.

   /**
    * This method will receive two ints passed in by the
    * user, and will return the larger of the two values.
    *
    * @param   val1    The first int value received
    * @param   val2    The second int value received
    * @return          The larger value of the two received
    */
    public static int getMax(int val1, int val2)
    {
        if(val1 > val2){
            return val1;
        }
        else{
            return val2;
        }
    }

List the parameter tags first, include the parameter's variable name, and a brief description of what the variable holds. The @return tag doesn't need a variable name, but should describe what is being returned. You do NOT need @return tags for void methods, or @param tags for methods that don't receive any parameters. Within the method, include short comments using the // marker, to indicate things that are being set or changed.

RUNNING JAVADOC

You may run Javadoc on your programs and look at the resulting documentation. It will produce several HTML files describing your classes based on the comments that you include. The steps listed below differ depending on whether you are using Unix (FAS) or working on your home machine, so follow the correct listing for your situation. It will be essential, particularly on Unix, to perform these steps and type the commands exactly; you may wish to simply highlight each command in your browser window, click Edit/Copy, and then paste the text into your telnet window.

Running Javadoc on Unix:

• In your root directory, make a new directory named public_html with this command:
  is02~%  mkdir public_html
• Next, change into the public_html directory, and make a directory there named docs:
  is02~%  mkdir docs
• Run this command to make files in this directory viewable in a browser:
  is02~%  fixwebfiles
• Set this directory to be viewable on the web with this command:
  is02~%  chmod 755 docs

Now, change directories and go inside the directory containing your java files. To run Javadoc on a specific file, type this command:

• is02~% javadoc  -d   ~/public_html/docs   YourFileName.java

This will create the javadoc files in your docs directory in public_html (the '-d' flag tells the javadoc compiler where to put the files). You'll see a few messages as the files are created. If you want to run javadoc on the entire directory, change to a location just outside it, and instead of typing a single filename in the javadoc command, type the directory name.

Once this has processed, change directories and go inside your docs directory - there's one more thing to do to make the individual files viewable...

• is02~% chmod  644  *.html

The chmod command (a Unix command) sets the permissions on your files to determine who can view them and through what mechanism. Note that directories will be set with the number 755, while files (ANY text or HTML file, or java file) will be set with the number 644.

Now you can open a web browser and go look at your docs directory. This will be located at:
http://www.people.fas.harvard.edu/~yourUserName/docs/
Replace 'yourUserName' with your FAS login name - keep the '~' there. This should show you a listing of the javadoc files generated for your program(s). If you'd like to make javadoc files for many of your programs, you may wish to rename (or make) your directories for each unit: unit2docs, unit3docs, etc., and then the web address or other commands will include the new directory name instead of docs/. You only need to make the public_html directory and run 'fixwebfiles' once; if you want multiple directories, you'll repeat the steps to make them and run 'chmod' on them.

Running Javadoc on Your Home PC:

This will be much easier than all the above, but you'll only be able to view your javadoc files on your local computer system.

• First, create a new folder at the same level as the folder containing your java files (or inside that directory) and name it docs (or whatever name you want).
  
  
• Second, in your DOS window, change into the directory containing your java files, and run the javadoc command to create the documentation pages:
  javadoc   -d   C:\pathToYour\docs  YourFileName.java
  If you used a different name than docs, substitute it above and include the correct path.
  
  
• Change into your docs directory, and click on the file you wish to see; it should open automatically in your browser, since it's an HTML file.

If you want to see your files on FAS, you'll need to create the directory structure described above, then FTP all your doc files up into those directories and change their permissions with the chmod command.