JavaDoc Command Tutorial For Java Documentation – POFTUT

JavaDoc Command Tutorial For Java Documentation

javadoc is a tool that is provided by the Java Development Kit (JDK) in order to create documents from the Java source code. The documentation is generally created in HTML format where the content is read from the source code file. Source code file generally has .java extension.

Sample Java Code

During learning the javadoc we will use the following Java source code example which has basic class, function, variable, etc to show examples.

Sample Java Code

Sample Java Code

javadoc Command Syntax

javadoc command has the following simple syntax which has packages, source files, options, and argfiles.

  • javadoc is the command which will generate java source code documentation.
  • PACKAGE|SOURCE_FILE is the package or source file name in which documentation will be generated.
  • OPTIONS enables different behavior of javadoc
  • @ARGFILES are used to provide arguments to the javadoc command.

JavaDoc Comments

As stated previously javadoc comments are created by using multi-line comments and putting some tags in order to provide some data. We will use /* for the start of the javadoc comments and */ end of the comments. Also * is used between /* and */ in order to make the comment as JavaDoc comment. If not used it will be assumed as a normal comment.

JavaDoc Comments

JavaDoc Comments

JavaDoc vs Single-Line vs Multi-Line Comments

Before starting JavaDoc we have to distinguish different types of comments in Java programming language. Let’s examine the following comment type JavaDoc, Single-Line and Multi-Line.

JavaDoc Tags

JavaDoc uses tags in order to identify the documents. Tags will start with the @ sign and then the tag name comes. Here is the basic syntax for the tag.

  • TAG_NAME is the name of the tag like author, code, exception, param, etc.
  • TAG_VALUE is the value of the tag which documents the given tag.

List Of JavaDoc Tags

Below you can find popular and useful JavaDoc tags.

Tag Description Syntax
@author Used for the author or developer name. @author name-text
{@code} Displays text in code font without interpreting the text as HTML markup or nested javadoc tags. {@code text}
{@docRoot} Represents the relative path to the generated document’s root directory from any generated page. {@docRoot}
@deprecated Add warning about the given entity like class, function or interface will be absolute in the future versions @deprecated deprecatedtext
@exception Adds a Throws subheading to the generated documentation, with the classname and description text. @exception class-name description
{@inheritDoc} Inherits the document from the superclass. This can be useful for class inheritance Inherits a comment from the immediate surperclass.
{@link} Inserts an in-line link with the visible text label that points to the documentation for the specified package, class, or member name of a referenced class. {@link package.class#member label}
{@linkplain} Identical to {@link}, except the link’s label is displayed in plain text than code font. {@linkplain package.class#member label}
@param Adds a parameter with the specified parameter-name followed by the specified description to the “Parameters” section. @param parameter-name description
@return Adds a “Returns” section with the description text. @return description
@see Adds a “See Also” heading with a link or text entry that points to reference where we can add more explanation. @see reference
@serial Used in the doc comment for a default serializable field. @serial field-description | include | exclude
@serialData Documents the data written by the writeObject( ) or writeExternal( ) methods. @serialData data-description
@serialField Documents an ObjectStreamField component. @serialField field-name field-type field-description
@since Adds a “Since” heading with the specified since-text to the generated documentation to set the creation or change date of the Java source code. @since release
@throws The @throws and @exception tags are synonyms. They can be used interchangeably. @throws class-name description
{@value} When {@value} is used in the doc comment of a static field, it displays the value of that constant. {@value package.class#field}
@version The version information about the application or source code will be added with this tag. @version version-text

Set Author Name, Version, Release Date

We will start with a simple example where we will put Author Name, Version and Release  Date documentation inside the Java source code.

Set Author Name, Version, Release Date

Set Author Name, Version, Release Date

Generate Documentation with javadoc Command

We have a basic Java source code that contains javadoc documentation. We will use the command line javadoc command and provide the Java source code file name which is HelloWorld.java in this example.

Generate Documentation with javadoc Command

Generate Documentation with javadoc Command

The output provides detailed information about javadoc creation. First, the HelloWorld.java source code file is loaded and the comments are parsed. Then all javadoc related documents will be generated as HTML files. If there is an error or warning it will be displayed at the end of the javadoc generation.

The generated HTML documentation file will be named as HelloWorld.html. It will look like below.

Generate Documentation with javadoc Command

Generate Documentation with javadoc Command

Alternatively, we can generate multiple Java source code files documentation by providing the path or directory with a glob sign like below.

Put Generated Document Into Specified Directory

By default using javadoc command, the generated documents will be put to the source code directory. We can also use a specific directory in order to store the documentation. We will use the -d option by providing the new documentation path. In the following example, we will set the documentation path as doc.

Documenting Java Class

Java class can be documented by using @link, @author tags like below. In the following example, we will set the class author name and the link for the class hierarchy.

Documenting Java Field

We can also document for specific fields and variables like below.

Documenting Java Method/Function

We can use @param,@return,@see,@since tags in order to put some documents about the method or function.

  • @param will provide information about the parameters. We will provide the parameter name and the explanation of the parameter in the same line.
  • @return is used to provide function return information.
  • @see is used to provide some links about the function.
  • @since is used to set the creation or release date of the function.

Documenting Java Method/Function

Documenting Java Method/Function

Create A Custom Tag

Even Java provides a lot of useful tags in order to document Java source code we may need to use some extra or non-existing tags to describe source code. We can create a custom tag easily with the following syntax during the javadoc execution and use it in the Java source code.

  • TAG_NAME is the newly created tag name.
  • LOCATION_ALLOWED is used to set where this tag can be used. a means everywhere.
  • HEADER is the category or header of the tag where this tag content will be shown in the generated document.

In the following example, we will create a tag called location which is used to set information about the source code physical location.

In order to use custom tag in the generated Java document, we will provide the custom tag creation command as a parameter to the javadoc command like below.

Create A Custom Tag

Create A Custom Tag

Styling Generated Documentation with CSS

Print JavaDoc Tree Structure

Generating JavaDoc In Eclipse

Leave a Reply

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