Java Documentation - Java

What is Java Documentation Comments?

The Java language supports three types of comments –

Sr.No.

Comment & Description

1

/* text */

The compiler ignores everything from /* to */.

2

//text

The compiler ignores everything from // to the end of the line.

3

/** documentation */

This is a documentation comment and in general its calleddoc comment. TheJDK javadoctool usesdoc commentswhen preparing automatically generated documentation.

This chapter is all about explaining Javadoc. We will see how we can make use of Javadoc to generate useful documentation for Java code.

What is Javadoc?

Javadoc is a tool which arises with JDK and it is used for producing Java code certification in HTML format from Java source code, which needs documentation in a predefined format.

Following is a simple example where the lines inside /*….*/ are Java multi-line comments. Similarly, the line which preceeds // is Java single-line comment.

Example

You can include required HTML tags inside the description part. For instance, the following example makes use of <h1>....</h1> for heading and <p> has been used for creating paragraph break −

Example

The javadoc Tags

The javadoc tool recognizes the following tags −

Tag

Description

Syntax

@author

Adds the author of a class.

@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

Adds a comment indicating that this API should no longer be used.

@deprecated deprecatedtext

@exception

Adds aThrowssubheading to the generated documentation, with the classname and description text.

@exception class-name description

{@inheritDoc}

Inherits a comment from thenearestinheritable class or implementable interface.

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.

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

@since release

@throws

The @throws and @exception tags are synonyms.

@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

Adds a "Version" subheading with the specified version-text to the generated docs when the -version option is used.

@version version-text

Example

Following program uses few of the important tags available for documentation comments. You can make use of other tags based on your requirements.

The documentation about the AddNum class will be produced in HTML file AddNum.html but at the same time a master file with a name index.html will also be created.

Now, process the above AddNum.java file using javadoc utility as follows –

You can check all the generated documentation here − AddNum. If you are using JDK 1.7 then javadoc does not generate a great stylesheet.css, so we suggest to download and use standard stylesheet from https://docs.oracle.com/javase/7/docs/api/stylesheet.css

All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

Java Topics