Comments in java

Let’s learn comments in java.

Comments in java

Comments are description added by programmer to provide information about a method, class or variable. Comments are not executed and ignored by compiler. Types of comments in java.

Single line comment (// comments)
Multi line comment (/* comments */)
Documentation comment (/** documentation */)

Single line comment in java

Single line comment start with two forward slash(//) and it is used to comment only single line.

Example:

// integer variable ‘a’ is assigned value 5
int a = 5;

Multi line comment in java

Multiline comment starts with forward slash star ( /* ) and ends with star forward slash ( */ ).

Multiline comment will comment out everything in between /* and */. Java compiler will completely ignore.

Syntax:

/*
This is
an example for
java multiline comment
*/


Example:
/* Here we are declaring and
printing integer variable b. */
int b = 5;
System.out.println(b);

Documentation comments

Java documentation comment is mainly used to create documentation Application Programming Interface(API).

Javadoc is a tool in java comes with JDK and used for generating java code documentation in HTML format from java source code.

Example:

/**
* <h1>Area of Square</h1>
* Area of Square java program calculates area
* using given side value and prints the area.
* <p>
* <b>Note: Adding comments in a java program makes it more
* user friendly and is presumed as good quality code
* 
* @author Sachin
* @version 1.0
* @since 2015-04-12
* </b>
* </p>
*/


public class DocumentationComment
{
   public static void main(String[] args)
   {
      double side = 5;
      double area = side * side;
      System.out.println("Area of square is : " + area);
   }
}

Output:

Area of Square is : 25.0

Compile above java program: javac Documentation.java

create documentation API by javadoc tool: javadoc Documentation.java

Javadoc tags – comments in java

Here are some available tags,

Syntax	Tag	Description
@return description	@return	adds a “Returns” section with the description text.
@exception class-name description	@exception	adds a Throws subheading to the generated documentation, with the classname and description text.
@author name-text	@author	adds the author of a class.
{@docRoot}	{@docRoot}	represents the relative path to the generated document root directory from any generated page.
{@code text}	{@code}	displays text in code font without interpreting the text as HTML markup or nested javadoc tags.
@deprecated deprecatedtext	@deprecated	adds a comment indicating that this API should no longer be used.
Inherits a comment from the immediate surperclass	{@inheritDoc}	inherits a comment from the nearest inheritable class or implementable interface.
@param parameter-name description	@param	adds a parameter with the specified parameter-name followed by the specified description to the “Parameters” section.
{@linkplain package.class#member label}	{@linkplain}	identical to {@link}, except the link’s label is displayed in plain text than code font.
{@link package.class#member label}	{@link}	inserts an in-line link with the visible text label that points to the documentation for the specified package, class, or member name of a referenced class.
@version version-text	@version	adds a “Version” subheading with the specified version-text to the generated docs when the -version option is used.
{@value package.class#field}	{@value}	when {@value} is used in the doc comment of a static field, it displays the value of that constant.
@throws class-name description	@throws	the @throws and @exception tags are synonyms.
@since release	@since	adds a “Since” heading with the specified since-text to the generated documentation.
@serialField field-name field-type field-description	@serialField	documents an ObjectStreamField component.
@serialData data-description	@serialData	documents the data written by the writeObject( ) or writeExternal( ) methods.
@serial field-description \| include \| exclude	@serial	used in the doc comment for a default serializable field.
@see reference	@see	adds a “See Also” heading with a link or text entry that points to reference.