SoftArchDoc:Javadoc Reference

Introduction

The Javadoc tools provides a powerful way to document Java classes, methods, fields, and packages. A utility within the Eclipse IDE can read Javadocs and then generate an HTML document based on the comments.

Purpose

The purpose of this document is to provide a reference for javadoc types, commonly used javadoc tags, and utilities that use javadoc in Eclipse.

Scope

The scope of this document is limited to javadoc comments.

References

Overview

The remainder of this document describes proper Javadoc documentation.

Types of Javadoc Comments

Class-level comments

Class level comments provide a description of a class, and they are placed right above the class declaration.

Figure 2-1 Sample class-level javadoc comment

Member-level comments

Member-level comments describe a class’s fields, methods, and constructors.

Figure 2-2 Sample member-level javadoc comment

Javadoc Tags

Standard Javadoc Tags

The most common javadoc tags are:

• @author: Describes the author of the document, and used in the class-level comments.
• @param parameter name description: Describes a parameter of a method or constructor. By convention, the first noun in the description is the data type of the parameter.
• @return: Describes the return type of a method. This text should describe the return type and permissible range of values.
• @throws classname description: The class-name is the name of the exception that may be thrown by the method. This tag is valid only in the doc comment for a method or constructor. The @throws documentation is copied from an overridden method to a subclass only when the exception is explicitly declared in the overridden method. The same is true for copying from an interface method to an implementing method. You can use {@inheritdoc} to force @throws to inherit documentation.
• @exception: Synonym for @throws

Other Javadoc Tags

• @deprecated deprecated-text -- Adds a comment indicating that the API shouldn’t be used. The Javadoc tool moves the deprecated-text ahead of the main description, placing it in italics and preceding it with a bold warning: "Deprecated". The first sentence of deprecated-text should at least tell when the API was deprecated and what to use as a replacement, because the Javadoc tool copies this first sentence to the summary section and index. You should include an {@link} tag (for Javadoc 1.2 or later) that points to the replacement API.
• {@link <FullClassName> [Display Text]} – Link to a class, where FullClassName is the name of the class you want to link to. Display text is optional – default text is the full name of the class.
• {@link #<MethodSignature> [Display Text]} – Link to a class method, where MethodSignature is the full signature of the target method including method name and parameter types.
• {@link <ClassName>#<MethodSignature> [Display Option]} – Link to method of another class . Must include package name if class is in another package.
• @linkplain – Identical to @link, only the link’s label is in plain text instead of code font
• @code -- Displays text in code font without interpreting the text as HTML markup or nested javadoc tags. This enables you to use regular angle brackets (< and >) instead of the HTML entities (< and >) in doc comments, such as in parameter types (<Object>), inequalities (3 < 4), or arrows (<-).
• @literal – Interprets text as the actual character instead of converting it into HTML. In plain text font instead of code font.
• @see reference -- Adds a "See Also" heading with a link or text entry that points to reference. The @see tag has three variations:

  • @see "string" -- The string is a book or other reference to information not available by URL. Must use double quotes surrounding the string. It does not generate a link.
  • @see <a href="URL#value">label</a> -- Adds a link as defined by URL#value. The URL#value is a relative or absolute URL. The Javadoc tool distinguishes this from other cases by looking for a less-than symbol (<) as the first character.
  • @see package.class#member label -- Adds a link, with visible text label, that points to the documentation for the specified member. The label is optional; if omitted, the member name appears instead as the visible text. Use -noqualifier to globally remove the package name from this visible text.

• @serial field-description | include | exclude -- Used in the doc comment for a default serializable field. An optional field-description should explain the meaning of the field and list the acceptable values. If needed, the description can span multiple lines. The standard doclet adds this information to the serialized form page. The include and exclude arguments identify whether a class or package should be included or excluded from the serialized form page. A public or protected class that implements Serializable is included unless that class (or its package) is marked @serial exclude. A private or package-private class that implements Serializable is excluded unless that class (or its package) is marked @serial include
• @serialField field-name field-type field-description -- Documents an ObjectStreamField component of a Serializable class's serialPersistentFields member. One @serialField tag should be used for each ObjectStreamField component.
• @serialData data-description -- The data-description documents the types and order of data in the serialized form. Specifically, this data includes the optional data written by the writeObject method and all data (including base classes) written by the Externalizable.writeExternal method. The @serialData tag can be used in the doc comment for the writeObject, readObject, writeExternal, readExternal, writeReplace, and readResolve methods.
• @since since-text -- Adds a "Since" heading with the specified since-text to the generated documentation. This tag means that this change or feature has existed since the software release specified by the since-text.
• {@value package.class#field} – Displays value of a constant field.
• @version version-text -- Adds a "Version" subheading with the specified version-text to the generated docs when the -version option is used. This tag is intended to hold the current version number of the software that this code is part of.
• {@docroot} – Relative path to the generated document’s root directory from any generated page. It is useful when you want to include a file, such as a copyright page or company logo, that you want to reference from all generated pages. Linking to the copyright page from the bottom of each page is common.
• {@inheritDoc} -- Inherits (copies) documentation from the nearest inheritable class or implementable interface into the current doc comment at this tag's location. This allows you to write more general comments higher up the inheritance tree, and to write around the copied text. Only valid in the main description block of a method or in the text arguments of a @return, @param, or @throws tag of a method.
• Any HTML tag can be included in javadoc comment.

Where Javadoc Allows Tags

Javadoc in Eclipse and HTML Document Generation in Eclipse

Configuring Javadoc in Eclipse

From the Open Seminar in Software Engineering website: “Eclipse generates Javadocs every time you create a class, method, or field, using templates built into the IDE. These templates can be modified to create Javadoc in the format that you want. Or you can turn off the Javadoc generation property. The Javadoc templates are found by selecting Window > Preferences. Under the tree on the left of the Preferences dialog, open up Java > Code Style > Code Templates. There is a check box at the bottom of the Code Templates page that says Automatically add comments for new methods and types. If you uncheck this box, Javadoc comments will not be generated. To configure generated comments, open the Comments tree. Select a type of comment to modify, and select Edit.... Text that looks like ${ } is a variable. Use the Insert Variable... button to see what variables are avaliable to you.”

Generating an HTML document from within Eclipse

From the Open Seminar in Software Engineering website: “* Right click on the project and select Export.... Select Javadoc, and click Next.

• Make sure the Javadoc command refers to the Javadoc command line tool. This tool is provided with JDK. The name is usually javadoc.exe. In the lab, you can find javadoc.exe in C:\j2sdk1.4.2\bin\ (that is, the Javadoc command is C:\j2sdk1.4.2\bin\javadoc.exe .)
• Select the types that you want to create Javadoc for.
• Make sure that the Use Standard Doclet radio button is chosen, and Browse for a destination folder.
• Click Next for more options if you wish; otherwise click Finish.”

Conclusion

Javadoc comments are a powerful way to document code. They are easy to read and may contain hyperlinks, class references, and inherit from other class javadoc comments. Proper use of javadocs can provide other developers with a clear description of Java classes, fields, and methods, and are a good best practice for documenting code.