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);
        }

}

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

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.

/**
 * @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);
        }

}

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

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.

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);
        }

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.

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

Styling Generated Documentation with CSS

Print JavaDoc Tree Structure

Generating JavaDoc In Eclipse