Tech-Freaks.in

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