Easy documentation with Javadoc

Easy documentation with JavaDoc

There’s probably nothing programmers hate more than documenting their code. Even doing timesheets takes second place on the list of things programmers hate to do.

Fortunately help is at hand.

The developers of Java recognised the problem and made life easy for us. They developed a tool called javadoc which generates standard HTML documentation from comments we write in our Java source code.

Javadoc really is easy

The javadoc tool has been available in the JDK since version 1.0. All the standard Java API documentation has been generated with it, so you should already be familiar with the output (you do read the API documentation, don’t you?).

All we need to do is to write specific Javadoc comments while we are developing our code (you do comment your code, don’t you?). A Javadoc comment start with a /** and end with a */, and can span as many lines as we need. The Javadoc comment must be placed before the declaration of a class, a field, a constructor, and/or a method. We can also include HTML tags within the Javadoc comments.

Within our Javadoc comments, we can also add additional Javadoc tags. The javadoc tags generate additional information from our source code. These tags all start with an @ sign. A tag must start at the beginning of a line (after any leading spaces and an optional asterisk).

Examples of these case-sensitive tags include:

  • @author
  • @deprecated
  • @exception
  • @param
  • @return
  • @see
  • @since
  • @throws
  • @version

A simple Javadoc example

Here’s a simple example:


/**
 * A class representing an employee. This is a model 
 * object within our domain.
 * The domain class hierarchy is as follows:
 * 
 *
 * @author  John Smith
 * @version 3.14
 * @see     com.example.Person
 */

public class Employee extends Person {
   ...
}

A simple example of a method comment follows:

/**
 * Converts the string argument containing a signed decimal
 * integer into an {@code int} value.
 *
 * @param str  a {@code String} containing the decimal 
 * number to be converted.
 * @return     the {@code int} value represented by 
 * the argument.
 * @exception  NumberFormatException  if the string 
 * cannot be converted to a decimal number.
 */

public int convert(String str) throws NumberFormatException {
   ...
}

Watch out for proper sentence construction and punctuation! The first sentence (ending with the first period) will be used as the description in the summary section, while the entire Javadoc comment will be used in the detail section.

How Javadoc works

We can run javadoc on whole packages and/or individual source files. The javadoc tool parses the declarations, Javadoc comments and tags in our source code, and generates a set of corresponding HTML pages. These describe the public and protected classes (by default; this can be changed), nested classes, interfaces, fields, constructors and methods. When generating HTML documentation, javadoc adds additional cross-reference links to documented elements such as:

  • Declarations (return types, argument types, and field types).
  • See Also sections that are generated from @see tags.
  • Exceptions generated from @throws tags.
  • Summary tables of packages, classes and members.
  • Package and class inheritance trees.
  • The index file.

If we’re disciplined when writing code (you are a disciplined programmer, right?), we can reduce the burden of writing code documentation afterwards. An added benefit is that our documentation will have the same format as all the other standard Java API documentation out there, and can be easily used by other Java programmers.

For further information on how to use javadoc, Javadoc tags and javadoc options, please refer to the JDK tool documentation.

I’m always interested in your opinion, so please leave a comment. Your feedback helps me write tips that help you.

Leave a Comment

Your email address will not be published. Required fields are marked *

Code like a Java Guru!

Thank You

We're Excited!

Thank you for completing the form. We're excited that you have chosen to contact us about training. We will process the information as soon as we can, and we will do our best to contact you within 1 working day. (Please note that our offices are closed over weekends and public holidays.)

Don't Worry

Our privacy policy ensures your data is safe: Incus Data does not sell or otherwise distribute email addresses. We will not divulge your personal information to anyone unless specifically authorised by you.

If you need any further information, please contact us on tel: (27) 12-666-2020 or email info@incusdata.com

How can we help you?

Let us contact you about your training requirements. Just fill in a few details, and we’ll get right back to you.

Your Java tip is on its way!

Check that incusdata.com is an approved sender, so that your Java tips don’t land up in the spam folder.

Our privacy policy means your data is safe. You can unsubscribe from these tips at any time.