top

Search

Java Tutorial

There are three kinds of comments in the Java language − Sr.No.Comment & Description1./* My Java block comments*/The java compiler ignores everything from /* to */.2.//My Java single line commentsSingle line comment starts with two forward slashes with no white spaces (//) and lasts till the end of line. If the comment exceeds one line, then put two more consecutive slashes on the next line and continue the comment.The Java compiler ignores everything from // to the end of the line.3./** My Java documentation comments*/This is a java documentation comment and is generally called doc comment. When preparing automatically produced documentation, the JDK javadoc tool utilizes doc comments.Javadoc is a tool that comes with JDK and is used to generate Java code documentation from Java source code in HTML format, which needs predefined format documentation. Following is a straightforward instance/example where Java multi-line comments are the lines inside /* .... */. Similarly, Java's single-line comment is the line that precedes //. Example: /* * The MyHelloWorldProgramprogram is a program   * that simply displays "My name is John!" to the standard  * output.  *  */ public class MyHelloWorldProgram {  public static void main(String[] args){  // Prints My name is John! on standard output.       System.out.println("My name is John!");     }  } Inside the description section, you can include necessary HTML tags. For example, < h1> .... </h1 > for heading is used in the following example and < p > is used to create paragraph break − Example: /** * <h 1> Hello, World! </h 1> * The MyHelloWorldProgramprogram implements an application   * that simply displays "My name is John!" to the output. * <p> * Giving proper comments in your program makes it more * user friendly and it is assumed as a high quality code. * </p> */  public class MyHelloWorldProgram { public static void main(String[] args){ /* Prints My name is John!"! on standard output.       System.out.println("My name is John!");    } } The javadoc tool acknowledges the tags below − TagDescriptionSyntax@authorAdds the author of a class.@author name-text{@code}Displays text in code font without interpreting the text as HTML markup or nested javadoc tags.{@code text}{@docRoot}Represents the relative path to the generated document's root directory from any generated page.{@docRoot}@deprecatedAdds a comment indicating that this API should no longer be used.@deprecated deprecatedtext@exceptionAdds a Throws subheading to the generated documentation, with the classname and description text.@exception class-name description{@inheritDoc}Inherits a comment from the nearest inheritable class or implementable interface.Inherits a comment from the immediate surperclass.{@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.{@link package.class#member label}{@linkplain}Identical to {@link}, except the link's label is displayed in plain text than code font.{@linkplain package.class#member label}@paramAdds a parameter with the specified parameter-name followed by the specified description to the "Parameters" section.@param parameter-name description@returnAdds a "Returns" section with the description text.@return description@seeAdds a "See Also" heading with a link or text entry that points to reference.@see reference@serialUsed in the doc comment for a default serializable field.@serial field-description | include | exclude@serialDataDocuments the data written by the writeObject( ) or writeExternal( ) methods.@serialData data-description@serialFieldDocuments an ObjectStreamField component.@serialField field-name field-type field-description@sinceAdds a "Since" heading with the specified since-text to the generated documentation.@since release@throwsThe @throws and @exception tags are synonyms.@throws class-name description{@value}When {@value} is used in the doc comment of a static field, it displays the value of that constant.{@value package.class#field}@versionAdds a "Version" subheading with the specified version-text to the generated docs when the -version option is used.@version version-textExample: The program that follows utilizes a few of the significant tags accessible to comments for the documentation. Based on your demands, you can use other tags also. The MultiplyNum class documentation will be produced in the MultiplyNum.html i.e. a HTML file, but at the same time a master file with an index.html name will also be created. import java.io.*;  /** * <h 1>Multiply 2 Numbers!</h 1>  * The MultiplyNumprogram implements an application that  * simply multiply two given integer numbers and Prints  * the output on the screen.  * <p>  * <b>Note:</b> Giving proper comments in your program makes it more  * user friendly and it is assumed as a high quality code.  *  * @author  John Walter  * @version 2.0  * @since   2019-03-16  */  public class MultiplyNum{ /**     * This method is used to multiply two integers. This is     * a the simplest form of a class method, just to     * show the usage of various javadoc Tags.     * @param numA This is the first paramter to multiplyNum      * method     * @param numB  This is the second parameter to multiplyNum          method     * @return int This returns multiplication of numA and numB.     */ public int multiplyNum (int numA,int numB){  return numA * numB;  }  /**    * This is the main method which makes use of addNum method.     * @param args Unused.     * @return Nothing.     * @exception IOException On input error.     * @see IOException     */ public static void main(String args[])throws IOException{  MultiplyNum obj =new MultiplyNum();  int result = obj. multiplyNum(10,20);  System.out.println("Multiplication of 10 and 20 is :"+ result);  }  } Now, process the above MultiplyNum.java file using javadoc utility as follows – $ javadoc MultiplyNum.java
logo

Java Tutorial

Java Documentation

There are three kinds of comments in the Java language − 

Sr.No.Comment & Description
1./* My Java block comments*/

The java compiler ignores everything from /* to */.
2.//My Java single line comments

Single line comment starts with two forward slashes with no white spaces (//) and lasts till the end of line. If the comment exceeds one line, then put two more consecutive slashes on the next line and continue the comment.

The Java compiler ignores everything from // to the end of the line.
3./** My Java documentation comments*/

This is a java documentation comment and is generally called doc comment. When preparing automatically produced documentation, the JDK javadoc tool utilizes doc comments.

Javadoc is a tool that comes with JDK and is used to generate Java code documentation from Java source code in HTML format, which needs predefined format documentation. 

Following is a straightforward instance/example where Java multi-line comments are the lines inside /* .... */. Similarly, Java's single-line comment is the line that precedes //. 

Example

/* 
* The MyHelloWorldProgramprogram is a program  
* that simply displays "My name is John!" to the standard 
* output. 
* 
*/ 
public class MyHelloWorldProgrampublic static void main(String[] args){ 
// Prints My name is John! on standard output. 
      System.out.println("My name is John!"); 
   } 
} 

Inside the description section, you can include necessary HTML tags. For example, < h1> .... </h1 > for heading is used in the following example and < p > is used to create paragraph break − 

Example

/** 
* <h 1> Hello, World! </h 1> 
* The MyHelloWorldProgramprogram implements an application  
* that simply displays "My name is John!" to the output. 
* <p> 
* Giving proper comments in your program makes it more 
* user friendly and it is assumed as a high quality code. 
* </p> 
*/ 
public class MyHelloWorldProgram { 
public static void main(String[] args){ 
/* Prints My name is John!"! on standard output. 
      System.out.println("My name is John!"); 
   } 
} 

The javadoc tool acknowledges the tags below − 

TagDescriptionSyntax
@authorAdds the author of a class.@author name-text
{@code}Displays text in code font without interpreting the text as HTML markup or nested javadoc tags.{@code text}
{@docRoot}Represents the relative path to the generated document's root directory from any generated page.{@docRoot}
@deprecatedAdds a comment indicating that this API should no longer be used.@deprecated deprecatedtext
@exceptionAdds a Throws subheading to the generated documentation, with the classname and description text.@exception class-name description
{@inheritDoc}Inherits a comment from the nearest inheritable class or implementable interface.Inherits a comment from the immediate surperclass.
{@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.{@link package.class#member label}
{@linkplain}Identical to {@link}, except the link's label is displayed in plain text than code font.{@linkplain package.class#member label}
@paramAdds a parameter with the specified parameter-name followed by the specified description to the "Parameters" section.@param parameter-name description
@returnAdds a "Returns" section with the description text.@return description
@seeAdds a "See Also" heading with a link or text entry that points to reference.@see reference
@serialUsed in the doc comment for a default serializable field.@serial field-description | include | exclude
@serialDataDocuments the data written by the writeObject( ) or writeExternal( ) methods.@serialData data-description
@serialFieldDocuments an ObjectStreamField component.@serialField field-name field-type field-description
@sinceAdds a "Since" heading with the specified since-text to the generated documentation.@since release
@throwsThe @throws and @exception tags are synonyms.@throws class-name description
{@value}When {@value} is used in the doc comment of a static field, it displays the value of that constant.{@value package.class#field}
@versionAdds a "Version" subheading with the specified version-text to the generated docs when the -version option is used.@version version-text

Example: 

The program that follows utilizes a few of the significant tags accessible to comments for the documentation. Based on your demands, you can use other tags also. 

The MultiplyNum class documentation will be produced in the MultiplyNum.html i.e. a HTML file, but at the same time a master file with an index.html name will also be created. 

import java.io.*; 
/** 
* <h 1>Multiply 2 Numbers!</h 1> 
* The MultiplyNumprogram implements an application that 
* simply multiply two given integer numbers and Prints 
* the output on the screen. 
* <p> 
* <b>Note:</b> Giving proper comments in your program makes it more 
* user friendly and it is assumed as a high quality code. 
* 
* @author  John Walter 
* @version 2.0 
* @since   2019-03-16 
*/ 
public class MultiplyNum{ 
/** 
   * This method is used to multiply two integers. This is 
   * a the simplest form of a class method, just to 
   * show the usage of various javadoc Tags. 
   * @param numA This is the first paramter to multiplyNum  
   * method 
   * @param numB  This is the second parameter to multiplyNum          method 
   * @return int This returns multiplication of numA and numB. 
   */ 
public int multiplyNum (int numA,int numB){ 
return numA * numB; 
} 
/** 
   * This is the main method which makes use of addNum method. 
   * @param args Unused. 
   * @return Nothing. 
   * @exception IOException On input error. 
   * @see IOException 
   */ 
public static void main(String args[])throws IOExceptionMultiplyNum obj =new MultiplyNum(); 
int result = obj. multiplyNum(10,20); 
System.out.println("Multiplication of 10 and 20 is :"+ result); 
} 
} 

Now, process the above MultiplyNum.java file using javadoc utility as follows – 

$ javadoc MultiplyNum.java 

Leave a Reply

Your email address will not be published. Required fields are marked *