❮ Number Cos String Split ❯

Java Documentation Comments

Java supports three types of comments. The first two are // and /* /. The third is called documentation comments, which begin with / and end with */.

Documentation comments allow you to embed information about the program within the program itself. You can use the javadoc tool to generate this information and output it to HTML files.

Documentation comments make it easier for you to document your program information.

Javadoc Tags

The javadoc tool recognizes the following tags:

Tag	Description	Example
@author	Identifies the author of a class	@author description
@deprecated	Indicates an outdated class or member	@deprecated description
{@docRoot}	Specifies the path to the current document's root directory	Directory Path
@exception	Marks an exception thrown by a class	@exception exception-name explanation
{@inheritDoc}	Inherits comments from the immediate superclass	Inherits a comment from the immediate superclass.
{@link}	Inserts a link to another topic	{@link name text}
{@linkplain}	Inserts a link to another topic, but the link is displayed in plain text	Inserts an in-line link to another topic.
@param	Describes a method's parameter	@param parameter-name explanation
@return	Describes the return type	@return explanation
@see	Specifies a link to another topic	@see anchor
@serial	Describes a serializable field	@serial description
@serialData	Describes data written by the writeObject( ) and writeExternal( ) methods	@serialData description
@serialField	Describes an ObjectStreamField component	@serialField name type description
@since	Marks when a specific change was introduced	@since release
@throws	Same as the @exception tag.	The @throws tag has the same meaning as the @exception tag.
{@value}	Displays the value of a constant, which must be a static field.	Displays the value of a constant, which must be a static field.
@version	Specifies the version of the class	@version info

Documentation Comments

After the initial /*, the first few lines are the main description of the class, variables, and methods.

Following this, you can include one or more various @ tags. Each @ tag must start on a new line or immediately follow an asterisk (*).

Multiple tags of the same type should be grouped together. For example, if you have three @see tags, you can place them one after the other.

Here is an example of a class documentation comment:

/**
* This class draws a bar chart
* @author tutorialspoint
* @version 1.2
*/

What Javadoc Outputs

The javadoc tool takes your Java program's source code as input and outputs HTML files containing your program's comments.

Information for each class will be in its own HTML file. Javadoc can also output inheritance trees and indexes.

Due to different implementations of javadoc, the behavior may vary. You need to check the details of your Java development system's version and choose the appropriate Javadoc version.

Example

Here is a simple example using documentation comments. Note that each comment precedes the item it describes.

After being processed by javadoc, the comments for the SquareNum class will be found in SquareNum.html.

SquareNum.java File Code:

import java.io.*;

/**
* This class demonstrates documentation comments
* @author Ayan Ahmed
* @version 1.2
*/
public class SquareNum {
   /**
   * This method returns the square of num.
   * @param num The value to be squared.
   * @return num squared.
   */
   public double square(double num) {
      return num * num;
   }
   /**
   * This method inputs a number from the user.
   * @return The value input by the user.
   */
   public double getNumber() {
      InputStreamReader isr = new InputStreamReader(System.in);
      BufferedReader br = new BufferedReader(isr);
      String input;
      try {
         input = br.readLine();
         return Double.parseDouble(input);
      } catch (Exception e) {
         System.out.println("Error: " + e.getMessage());
         return 0.0;
      }
   }
   /**
   * This method demonstrates square().
   * @param args Unused.
   */
   public static void main(String args[]) {
      SquareNum obj = new SquareNum();
      double val;
      System.out.println("Enter a number to be squared: ");
      val = obj.getNumber();
      val = obj.square(val);
      System.out.println("The square of the number is: " + val);
   }
}

/**
 * This is a multiline description. You can use
 * as many lines as you like.
 * @param num The value to be squared.
 * @return num squared.
 */
public double square(double num) {
   return num * num;
}
/**
 * This method inputs a number from the user.
 * @return The value input as a double.
 * @exception IOException On input error.
 * @see IOException
 */
public double getNumber() throws IOException {
   InputStreamReader isr = new InputStreamReader(System.in);
   BufferedReader inData = new BufferedReader(isr);
   String str;
   str = inData.readLine();
   return (new Double(str)).doubleValue();
}
/**
 * This method demonstrates square().
 * @param args Unused.
 * @return Nothing.
 * @exception IOException On input error.
 * @see IOException
 */
public static void main(String args[]) throws IOException
{
   SquareNum ob = new SquareNum();
   double val;
   System.out.println("Enter value to be squared: ");
   val = ob.getNumber();
   val = ob.square(val);
   System.out.println("Squared value is " + val);
}
}

To process the SquareNum.java file using the javadoc tool:

$ javadoc SquareNum.java
Loading source file SquareNum.java...
Constructing Javadoc information...
Standard Doclet version 1.5.0_13
Building tree for all the packages and classes...
Generating SquareNum.html...
SquareNum.java:39: warning - @return tag cannot be used\
                     in method with void return type.
Generating package-frame.html...
Generating package-summary.html...
Generating package-tree.html...
Generating constant-values.html...
Building index for all the packages and classes...
Generating overview-tree.html...
Generating index-all.html...
Generating deprecated-list.html...
Building index for all classes...
Generating allclasses-frame.html...
Generating allclasses-noframe.html...
Generating index.html...
Generating help-doc.html...
Generating stylesheet.css...
1 warning
$

❮ Number Cos String Split ❯