A Quick Introduction to Javadoc

1. What is Javadoc?
2. General format of Javadoc Comments
3. Tags
    3.1. Tags for Classes
    3.2 Tags for Methods
    3.3 Tags for Variables
4. Running Javadoc
    4.1. In the Labs
    4.2. At home
    4.3. Warning: Javadoc and BlueJ
    4.4. Sending output to another folder
5. Javadoc and HTML
6. More Information
 

1. What is Javadoc?
Traditionally, when you write a program you must write a separate document recording how the program works.  When the program changes, the separate documentation must change as well.  For large programs that are constantly being changed and improved, it is a tedious and error-prone task to keep the documentation consistent with the actual code.

Javadoc is a tool that helps with this problem.  Instead of writing and maintaining separate documentation, the programmer writes specially-formatted comments in the Java code itself.  Javadoc takes these comments and transforms them into documentation in HTML (web page) format.   For a short example of documentation generated by Javadoc, see the external documentation for our sample program.  Another good example of a program with Javadoc comments is the SavitchIn class, which is printed in an appendix to the text and also included in the CD which accompanies the text.  Here is the output you get when you run Javadoc on SavitchIn.  For a larger, real-life example of documentation generated by Javadoc, see the Java 1.3 API documentation.

In CISC 124, you are required to use Javadoc format for "header" comments -- that is, the block comments that appear at the top of each file and before the declaration of each class, method and top-level variable.  There are two reasons for this requirement:

1. the format forces you to be precise and complete
2. it starts you in the habit of using Javadoc format, which is a widely-accepted industry standard

2. General format of Javadoc Comments

All Javadoc comments have the following format:
    /**
     * Summary sentence.
     * More general information about the
     * program, class, method or variable which
     * follows the comment, using as many lines
     * as necessary.
     *
     * zero or more tags to specify more specific kinds
     * of information, such as parameters and return
     * values for a method
     */

You start out with the normal beginning of comment delimiter (/*) followed by another (*).  All following lines start with an asterisk lined up under the first asterisk in the first line.  The last line contains just the normal end of comment delimiter (*/).  The first sentence is a "summary sentence".  This should be a short description of the program, class, method or variable that can stand on its own.  Even though it's refered to as a "summary sentence", it is often a phrase rather than a complete sentence, as in the example below.  It can extend over several lines if needed; just don't include any blank lines.  (It ends with the first period, so you must avoid using abbreviations such as "e.g." in this sentence!)  Following the summary sentence, you may include more sentences to give more details; again, don't include any blank lines.  Following this general description, there should be a blank line, then a sequence of "tags".  Different tags will be appropriate for different situations.  Here is an example of a Javadoc comment without tags which describes the variable declarated immediately below it:

    /**
     * The number of students in the class.  This variable must not be
     * negative or greater than 200.
     */
    public int numStudents;
 

Note: You still can and should have comments within methods, describing local variables and the computing going on inside the methods.  There is, however, no Javadoc format for these comments.  Use // or /*..*/, whichever you prefer.

3. Tags
The general form of a tag is:
    * @name comment
where the name of the tag specifies what kind of information we're giving and the comment gives the information.  For example, the author tag is used to tell us who wrote a class or program, as in
    * @author William Shakespeare
Each tag should start on a new line.  The tag comments can extend into multiple lines if necessary, but there should be no blank lines in between tags.

3.1. Tags for Classes
In a Javadoc comment before a class definition, you should have an author tag, specifying who wrote the program.
        @author         your full name, as it will appear in a class list (no nicknames, please), plus your lab section
For example:
        @author Jane Smith, lab X
If you worked with a partner, make an author tag for each one of you, on separate lines.
 

3.2 Tags for Methods
For each parameter to a method, include a param tag:
        @param <name of parameter>      short description of parameter
For example,
    * @param size number of elements in the array
If a method has several parameters, the param tags should appear in the same order as the parameters are declared.  A method with no parameters will have no param tags.

After the param tag(s), if any, include a return tag unless your return type is void (no return value):
        @return    short description of return value
For example:
    * @return true if the value was found in the array

If your method throws an exception, you should also include an exception tag:
        @exception <name of exception>     description of circumstances under which the exception is thrown
For example:
    * @exception NumberFormatException raised if the user's input is not in valid integer format
If your method throws more than one exception, they should appear in alphabetical order by exception name.  Exception tags should follow param and return tags.

3.3 Tags for Variables
A Javadoc comment before a variable declaration needs no tags.  See Section 2 for an example.

4. Running Javadoc
Javadoc is a DOS program without a fancy user interface.  The use of a batch file, however, makes it quite simple to run.

4.1. In the Labs
Download the file jdrun.bat into the folder containing your program.  Find the file using My Computer or Windows NT Explorer and double-click it.  It will create Javadoc output in that folder.

4.2. At home
To run Javadoc on your home computer, download the file JDathome.bat into the folder containing your program.  Use Notepad to edit this file and change c:\javafolder to the full name of your SDK installation folder.  If you have downloaded BlueJ at home, you will know where that folder is.  If you are using JBuilder (version 3 or later) at home, use the name of the folder in which you installed JBuilder plus \bin.  So, for example, if you've installed JBuilder into c:\JBuilder5, your SDK folder is c:\JBuilder5\bin.  Once you've made that change to the batch file, you can double-click on it to run it, just like in the labs.

4.3 Warning: Javadoc and BlueJ
Some of you may discover that you can run Javadoc directly from BlueJ.  This would be a great convenience, but unfortunately BlueJ doesn't use the Javadoc flags I want you to use.  Specifically, if you run BlueJ that way, your output will only contain information about public methods and variables.  That's what you want for most production programs, for generating user information, but it's not what we want for CISC 124; you need documentation for all of your code.  So you should use run Javadoc separately using one of the above batch files.

4.4. Sending output to another folder
When you run the batch files I've given, all of the Javadoc output (lots of files) is put in the folder containing your program.  Sometimes it's convenient to send the Javadoc output somewhere else.  To do this, add the switch
    -d <folder>
to the batch files, where <folder> is the name of the folder where you want the output to go.  It can be a full path name, or relative to the folder with the programs, so
    -d doc
will send the output to a sub-folder of the folder with the programs called doc.

5. Javadoc and HTML
You will notice that Javadoc does not retain the line breaks or extra spaces in your comments.  This is because Javadoc outputs HTML (HyperText Mark-up Language, the language in which web pages are written).  HTML formats paragraphs according to the width of the screen, ignoring line breaks and extra spaces in the source.  If you want some control over the formatting of your comments in the generated web pages, you can imbed HTML commands in your comments.

If you don't know HTML, here are 3 HTML commands that can be useful:

• <br> Forces a line break, so the next word appears at the beginning of a new line
• <p> Same as <br>, but skips a line first
• <pre> Marks the start of a "pre-formatted" section.  Everything between this command and the next </pre> command is reproduced in a fixed-point font, with spaces and line breaks preserved.
• </pre> Marks the end of a "pre-formatted" section.

If you already know HTML, you'll know how to produce some other effects, such as boldface type or  bulleted lists.  You can do this if you like, but don't waste too much time on it.  You will not get extra marks for fancy Javadoc output.  The emphasis here is on clear, accurate content.

6. More Information
This web page tells you all you really need to know about Javadoc for CISC 124.  There are, however, more tags and more things you can do with Javadoc.  For more complete information on Javadoc comments, plus lots of stylistic advice, see How to Write Doc Comments for Javadoc   You can also see the Javadoc Home Page for more information on how to run and customize Javadoc.  The Javadoc 1.2 Reference Page provides a good, concise description of both the comment format and how to run Javadoc, including the command-line options.

This page created by Margaret Lamb, Queen's University, Kingston, Ontario.  Last modified  .