Latest web development tutorials

Java Documentation Comments

Java annotations only three kinds of ways. The first two are // and / * * /, and the third is called the legend comment that begins with / **, end with * /.

Description Comment allows you to embed information about the program in the program. You can use the javadoc tool to generate information and output to HTML files.

Description Comment, you record more information regarding your program.

javadoc tag

javadoc tool recognizes the following tags:

label description Example
@author Identifies a class of authors @author description
@deprecated Named a member of the class or expired @deprecated description
{@docRoot} Path specified in the current document root directory Directory Path
@exception Mark a class exceptions thrown @exception exception-name explanation
{@inheritDoc} Directly from the parent class inherits comment Inherits a comment from the immediate surperclass.
{@link} Inserting a link to another topic {@link Name text}
{@linkplain} Insert a link to another topic, but the link is displayed in plain text font Inserts an in-line link to another topic.
@param Description of a method parameter @param parameter-name explanation
@return Return Type Description @return explanation
@see Specifies a link to another topic @see anchor
@serial A description of the sequence of property @serial description
@serialData Description Method written by writeObject () and writeExternal () data @serialData description
@serialField A description of the components ObjectStreamField @serialField name type description
@since When introducing a specific marker of change @since release
@throws And @exception same label. The @throws tag has the same meaning as the @exception tag.
{@value} Display value of a constant, the constant must be a static property. Displays the value of a constant, which must be a static field.
@version Version of the specified class @version info

Documentation Comments

After the start / **, the first line or lines is the main description of classes, variables and methods.

After that, you can include one or more of what sorts of @ tag. @ Each tag must be on a new line, or start at the beginning of a line followed by an asterisk (*).

A plurality of the same type of label should be placed into a group. For example, if you have three @see tags, they can be put together one by one.

The following is a description of an example of a class comment: 

/*** This class draws a bar chart.
* @author Zara Ali
* @version 1.2
*/

What javadoc output

javadoc tool your Java program's source code as input, output some HTML file containing your program annotations.

Each type of information will be alone in the HTML file. javadoc output can also be inherited tree and indexes.

Due to the different javadoc implementation work may be different, you need to check the version of your Java development system and other details, select the appropriate version of Javadoc.

Examples

The following is a comment that explains the use of a simple example. Note that the previous project each annotation in its description.

After javadoc treatment, SquareNum class notes will be found in the SquareNum.html. 

import java.io.*;
 
/**
* This class demonstrates documentation comments.
* @author Ayan Amhed
* @version 1.2
*/
public class SquareNum {
   /**
   * This method returns the square of num.
   * 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);
   }
}

As follows, using the javadoc tool to process SquareNum.java file: 

$ 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
$