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.

public class HelloWorld
{
        public static void main(String args[])
        {
                System.out.println("Hello World!");

                String name="Poftut.com";

                PrintHello(name);
        }

        public void PrintHello(String name)
        {
                System.out.println("Hello " + name);
        }

}
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 PACKAGE|SOURCE_FILE OPTIONS @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.

/*
 * @author      İsmail Baydan
 * @version     1.0
 * @since       2014-01-01
 *
 * 
*/

public class HelloWorld
{
        public static void main(String args[])
        {
                System.out.println("Hello World!");

                String name="Poftut.com";

                PrintHello(name);
        }

        public void PrintHello(String name)
        {
                System.out.println("Hello " + name);
        }

}
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.

//Single-Line Comment

/*
*Multi-line Comment
*/

/**
* JavaDoc Comment
*/

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 TAG_VALUE
  • `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.
LEARN MORE  What Is API (Application Programming Interface)?

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
LEARN MORE  What Is API (Application Programming Interface)?

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.

/**
 * @author      İsmail Baydan
 * @version     1.0
 * @since       2014-01-01
 *
 * */

public class HelloWorld
{
        public static void main(String args[])
        {
                System.out.println("Hello World!");

                String name="Poftut.com";

                PrintHello(name);
        }

        public void PrintHello(String name)
        {
                System.out.println("Hello " + name);
        }

}
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.

$ javadoc HelloWorld.java
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.

$ javadoc src/*

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.

$ javadoc -d doc src/*

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.

/**
* HelloWorld is the main entity we'll be using to . . .
* 
* Please see the {@link com.poftut.javadoc.Person} class for true identity
* @author İsmail Baydan
* 
*/

public class HelloWorld extends Person{

   // other fields and methods

}

Documenting Java Field

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

/**
 * The name of a person we will salute
 */

String name;

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.
         /**
         * @param name The name of the persone we want to salute
         *
         * @return will return void
         *
         * @see <a href="https://www.poftut.com">Poftut</a>
         *
         * @since 1.0
         *
         */
        public void PrintHello(String name)
        {
                System.out.println("Hello " + name);
        }

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:LOCATIONS_ALLOWED:HEADER
  • `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.
LEARN MORE  What Is API (Application Programming Interface)?

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

/**
 * @location Ankara 
 *
*/

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.

$ javadoc -tag location:a:"Locations" HelloWorld.java
Create A Custom Tag
Create A Custom Tag

Styling Generated Documentation with CSS

Print JavaDoc Tree Structure

Generating JavaDoc In Eclipse

Leave a Comment