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. DrJava
    4.2. Eclipse
5. Javadoc and HTML
6. More Information
 

1. What is Javadoc?
Good programmers include comments in their code to help others understand how their code works. This is particulary important for classes that will be used by others.  In most cases, it is hard to keep documentation up to date as code changes and also difficult to let others easily see your documenttion in a useful format.

Javadoc is a tool that helps with this problem. A programmer writes comments in the Java code according to some simple conventions.  Javadoc takes these comments and transforms them into documentation in HTML (web page) format.   You should be able to see Javadoc comments in programs given to you for your class.  (For example, in Picture2.java in CS101 in Fall 2008.)  You can see the output of Javadoc when you look at the Java API documentation for the standard library classes, for example for the String class.

The HTML comments can look very impressive, but it is not very hard to create comments in the proper format.  And, most Java IDEs (including DrJava and Eclipse) have a command to run Javadoc to create the HTML documentation. So do not be intimidated by this tutorial -- using Javadoc effectively is not difficult or more time-consuming than writing "normal" comments in your code.

Commenting using Javadoc may be required for your homework programs for several reasons.

1. Commenting programs is always good programming practice.
2. Your comments will help the instructor and TAs understand your code.
3. It starts you in the habit of using Javadoc format, which is a widely-accepted industry standard

When Javadoc is required for your homework, you must:

• Have a header comments at the start of each file, for the class defined in that file.  This must include description and the @author tag.
• Your Javadoc comment at the beginning of the "main" class file should briefly describe the entire program.
• You must have a comment for each method, including the description, a @param tag for each arguments, and a @return tag.
• When you create classes that have instance-variables (AKA fields) for the class, you must have a comment for each such variable.  (Not for local variables in method!)

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
There is a javadoc command-line program just like there is a javac and java program.   In our courses, it is easier to run Javadoc from inside your IDE (DrJava or Eclipse).   Using it from the command-line or within Eclipse allows you to choose many options to tailor your output.  DrJava gives fewer choices but produces useful output.

4.1. DrJava
Under the Tools menu, there are two commands:

• Preview Javadoc for Currrent Document:  this will generate Javadoc for the current Java file and show you this within DrJava
• Javadoc All Documents:  this will prompt for a folder name, and then create Javadoc HTML files in that folder for all Java files in the current folder.

Consult with your instructor about what you are expected to turn in.  It is quite possible that you do not need to submit Javadoc, and so previewing each of your Java files to make sure it looks good would be enough.

Note: by default, DrJava has settings so that comments are generated only for instance-variables and methods that are defined with public visibility (and the default or package visibility).   If you or your instructor want to see your private variables and methods in the HTML, go to Preference, choose Javadoc, and set "Access Level" to private.

4.2. Eclipse
Under the Project menu in Eclipse, there is a Javadoc command.  This will create the HTML documents in a folder in your current project. Look for a "docs" folder in your Package Explorer window.  You can open the index.html in that folder to see your Javadoc output.

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.  Dividing long comments into paragraphs with <p> is all that's really necessary to make your output clear.
• <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 your courses.  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.5 Reference Page provides a good, concise description of both the comment format and how to run Javadoc, including the command-line options.