How To Create API Documents In Java

Introduction

In this article we discuss how to create Application Programming Interface (API) documents in Java.

API Documents

For complete application development, developers need to work with third-party code. Now, in order to integrate the applications with the third-party code, programmers need well-written documentation, in other words API documentation.

It is a set of predefined rules and specifications that need to be followed by the programmer to use the services and resources provided by another software program.

How to create an API Document

By using the "javadoc" tool we can create a document API in Java. In the Java file, we must use the documentation comment /**......*/ to post information for the class, constructors, field, method, etcetera.

What is javadoc tool

The javadoc tool converts declarations and doc comments in Java source files and formats the public and protected API into a set of HTML pages.

In general, it creates a list of classes, a class hierarchy and an index of the entire API. As we pass arguments to javadoc, javadoc produces HTML pages by default for that.

How to comment the Source Code

Since javadoc automatically creates HTML web page, we can also add further documentation inside doc comments, including special formatting with HTML tags. Javadoc comments begin with (/**) and indicate text (provided by the programmer) to be included automatically in generated documentation.

/**
* This is a javadoc comment
*
*/

Using standard HTML in javadoc

We can also use standard HTML tags within a java-doc comment. However, we don't use heading tags such as <h1>, <h2> and <h6>, or a horizontal rule <hr>.

Example that shows document API

In this example; we can create a simple class that contains a documentation comment and shows how to create a document API.

package com.mypack;

/** User-defined class generated that contains only one method square.*/

Public Class APIDocEx

{

/** The square method prints square of the given number */

public static void square(int x)

{

System.out.println(x*x);

}

}

Output

To create the document API, we need to use the javadoc tool as in the following.

In a command prompt write the following:

javadoc M.java

Fig-1.jpg

After generating the documented API. We will now see many HTML files created. Now we need to open the index.html file to get the information about the classes. The figure below shows the following.

fig-2.jpg

Up Next
    Ebook Download
    View all
    Learn
    View all