Core Java

Adding Javadoc in programs

Javadoc is added in class and method header in order to provide insight about how the class or method behaves. Javadoc can be used in multiple ways either by going through the source code or publishing it by using the Javadoc tool that comes with the JDK.

One can describe as much about the class or method in javadoc comments and there are tags which can be used ti specify some particular information like exceptions, arguments and author. Moreover, one can use HTML inside javadoc comments. Following are some of the javadoc comments:

package com.example;

/** This is a Test class and the purpose is to show
 * various javadoc <br/><b>class</b> tags.
 *
 * @author Dummy
 * @since 2.4
 * @version 3.1
 */
public class Test{

	/** This method shows method level javadoc
	 *
	 * @param a is the int argument which is printed on the console
	 * @return Returns the value which is printed
	 * @see Object
	 * @throws RuntimeException when some improper scenario arises
	 */
	public int test(int a) throws RuntimeException{
		System.out.println(a);
		return a;
	}

	/** This method prints the default value
	 *
	 * @deprecated this version was deprecated as new version has been introduced
	 */
	 public void test(){
		 test(10);
	 }
}

The above code shows various javadoc tags as listed below:

@author : This tag specifies the developer name which is working on the code. This tag is applicable for class level only.
@since : The version of the library or framework in which the current class or method was introduced. This tag is applicable for class and method levels.
@version : The current version of the class. This tag is applicable for class level only.
@deprecated : Singnifies that this method or class should not be used and an alternative better version/option is available. This tag is applicable for class and method levels.
@param : The param tag specifies the argument of the method and tells the user what kind of value the method expects. This tag is applicable for method level only.
@return : Tells about the value which is returned from the method. This tag is applicable for method level only
@throws : This tag tells about the exception which is thrown by the method. This tag is applicable for method level only.
@see : This tag is used to refer to some other class or online reference to a web page which the user of the method can see to get more information. This javadoc tag can be used anywhere inside the code.
{@code} : Besides the above tags, one can use the code tag to format and display any code within the class.

Normally, the developers are not used to adding javadoc comments in the code and that is because of the fact that they don’t make it a habit to add javadoc comments in any piece of code that they write or maintain.

Other Java Tutorial
Answers to 50 Liferay Interview Questions
Database Interaction using Liferay
Serialization Questions

Comments

Leave Comment