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 documented 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 on the Source Code?
Since javadoc automatically creates an 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 the 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>.
An 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 documented API.
- package com.mypack;
- public Class APIDocEx
- {
- 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
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.