Tech-Freaks.in

• You understand the basics of Java but do not know how to understand and user third party libraries
• You are a Java programmer, and you trying to find out the way you can communicate to your collegues, how they can use the components created by you

This article is not for you, if:

• You are not aware of methods, classes etc of Java

What is an API document?
API document are also called Java docs and is used to communicate the low level programming interface to programmers. API docs highlight one of the important principles of OOPs, which is 'abstraction'. These documents gives only the programming interface and hide the complexity of the interface. In simple terms, it means, the API docs tells what arguments a method will take and what will be the result returned. However, it will not provide the details of how the result is reached.

Understanding elements in API document

Let us take the API document for J2SE 1.4 from Sun Java website.

The document with Frames are convenient to use.

You must have noticed that, the docs are divided into three sections.

• Package explorer
• Class and Interface explorer
• Description section

Let us dig deep with examples for each element to understand this better:

Package explorer

The left top section contains all the packages for the library in question. For this example, it is the packages present in J2SE 1.4 like java.lang, java.io etc. Clicking any of the package in the package explorer will provide only the list of classes & interface in the class explorer. Also, there is a 'All classes' link, which is show all the classes & interfaces in J2SE 1.4.

Class and Interface explorer

This section is present in the left bottom of the Java docs, just below the package explorer section. It shows all classes, interfaces, exceptions and errors present in the selected package. All interface names are italics styled for differenciation.

Description section

The description section contains all the details. When you click on a package, it shows the details of that package and when you click on a class/interface it shows the details of it.

Let us check an Interface. Click on the class List present in java.util package.
We get the following information reading the description section:

• List interface extends Collection interface
• It provide links to all known classes which implement this interface
• A detailed description of the interface itself
• Method summary provide the details of all the methods that are defined in the interface. The method summary provide the method signature and return type. Since the methods in an interface are by default abstract, we do not see this variation for List interface. For viewing details of a particular method we can click on that method. We can see the details of the method like what each argument means and what will be the logic of the method. For example, check the add(int, Object) method. It also provides details of the exceptions which the method throws.

Lets check the information displayed for a class. Let us take the Integer wrapper class present in java.lang.

• In the description top, the class name will be marked with abstract to indicate if the class in abstract class.
• The field summary shows any public instance variables present in the class. Example MAX_VALUE variable. Once clicking it, we see that this field is also defined as public static final variable.
• When you want to create an instance of a class, you need to know, which constructors are present for that class. How do we get this information? Constructor summary provides this information.
• The Integer wrapper class can be instantiated using String parameter or primitive int parameter. We get to know, that it does not have a empty constructor. So, Integer intTotal = new Integer(); will give compilation error. Clicking a constructor gives more information. We can see that the Integer constructor using String parameter throws a NumberFormatException, if the String is not parsable to integer.
• In the method summary, we see some methods marked as static. This helps us understand that the method can be called without creating an instance. For example intValue() is not marked static but parseInt is marked as static. So, we can use both the methods as below:

	Integer intObj = new Integer(10);
	int i = intObj.intValue();
	int j = Integer.parseInt("10");

• The method summary also shows if a particular method is abstract. 
• After the method summary, there are sections which show the methods which were inherited from parent class.

How to create an API document for your Java code?
 

Java docs are an excellent way to share code APIs related to your components to peer programmers who will be using it. Most IDEs provide an easy way to generate API documents for your application code. We will have a look at generating Java docs from command line.

First of all, we need to add appropriate comments in Java source code, so that it will be added in the generated Java docs. In the comments we need to add tags which will be added in Java docs. Below is a servlet code with Java doc comments.

package in.techfreaks.servlet;
import java.io.*;
import javax.servlet.http.*;
import javax.servlet.*;
/**
* This is a class comment which will be added in Java docs.
* @author Tech Freaks
*/
public class MyFirstServlet extends HttpServlet {
 /**
 * This method comment which will be added in Java docs.
 * This method is called when a form is posted to this servlet. It contains all the logic needed to be performed.
 * @param request HttpServletRequest object which is associated with this request.
 * @param response HttpServletResponse object
 * @throws ServletException which may occur while performing this operation
 * @throws IOException which may occur while performing the operations in this method.
 */
 public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
  String strErrMsg = "Please enter first name and last name";
  String strFirstName = request.getParameter("firstName");
  String strLastName = request.getParameter("lastName");
  if(strFirstName!=null && !strFirstName.equals("") && strLastName!=null && !strLastName.equals("")) {
   PrintWriter out = response.getWriter();
   out.println("Name : "+strFirstName+" "+strLastName);
  } else {
   request.setAttribute("errMsg", strErrMsg);
   request.getRequestDispatcher("../MyFirstJspPage.jsp").forward(request, response);
     }
 }
 public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
  doPost(request, response);
 }
}

Note the tags in class and method comments like @author, @param etc. The tags mentioned in the above example are just the basic tags. There are many different tags which can be added. The Java doc comments can also have HTML tags inside it, which will be reflected in the Java docs generated. Some of the tags like @author will not be added by default. They need to be specified with switch while running the 'javadoc' command. For all the switch available, run 'javadoc' command in command prompt without any parameter. Note that the J2SE/bin needs to be present in the path variable, if the javadoc command is to be run from any location. The below screenshot shows the javadoc command execution for in.techfreaks.servlet package with -author switch. This will generate the Java doc for the whole package. Since we have only have MyFirstServlet.java in this package, the API document for this servlet will be generated.

• Java doc comments always start with /** instead of /*. The /* are simple comments which will not be added into the generated Java docs.

Usage Guidelines: 

• Java docs should be used to understand low level programming APIs. They help understand how to use a class or interface without going through the source code.
• Java docs should not be used as an model artifacts to understand high level architecture.
• Java docs cannot be used in isolation to understand libraries and technologies. Other documentation is necessary to fully understand them.
  Example: Although the Java Docs for Servlet technology tell that for creating a servlet we need to extend javax.servlet.http.HttpServlet, it does not explains who needs to create the servlet instance and who calls the different methods like doGet, doPost etc. We need to understand the servlet specification to know this.

 Congratulations!! You have just received your passport to Java literacy!

Add your comment

Your name:
Subject:
Comment:
Word verification:
	Post Preview

yvComment v.1.20.0