Java document notes

May 10, 2021 Java

Java document notes

Java is just three ways to annotate. The first two are // and / s/, and the third is called a description note, which starts with /, and ends with .

Description comments allow you to embed information about the program in the program. You can use javadoc tool software to generate information and output it to HTML files.

Explain notes to make it easier for you to record information about your program.

javadoc tag

The javadoc tool software identifies the following tags:

Label	Describe	Example
@author	Identify the author of a class	@author description
@deprecated	Name an expired class or member	@deprecated description
{@docRoot}	Indicates the path to the current document root	Directory Path
@exception	Flags an exception thrown by a class	@exception exception-name explanation
{@inheritDoc}	Comments inherited from the direct parent class	Inherits a comment from the immediate surperclass.
{@link}	Insert a link to another topic	{@link name text}
{@linkplain}	Insert a link to another topic, but the link displays plain text fonts	Inserts an in-line link to another topic.
@param	Explains the parameters of a method	@param parameter-name explanation
@return	Explains the return value type	@return explanation
@see	Specify a link to another topic	@see anchor
@serial	Describes a serialized property	@serial description
@serialData	Describes the data written by the writeObject () and writeExternal () methods	@serialData description
@serialField	Explains an ObjectStreamField component	@serialField name type description
@since	Tags when a specific change is introduced	@since release
@throws	It'@exception like a label.	The @throws tag has the same meaning as the @exception tag.
{@value}	Displays the value of the constant, which must be a static property.	Displays the value of a constant, which must be a static field.
@version	The version of the specified class	@version info

Document comments

After the beginning/ , the first or few lines are the main descriptions of classes, variables, and methods.

After that, you can include one or more of the various hashtags. Each hashtag must be at the beginning of a new line or at the beginning of a line immediately following the asterisk.

Multiple labels of the same type should be grouped. For example, if you have @see labels, you can put them together one by one.

Here's an example of a class's description comments:

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

javadoc outputs what

The javadoc tool uses the source code of your Java program as input and outputs some HTML files that contain comments on your program.

The information for each class will be in a solo HTML file. javadoc can also output inherited tree structures and indexes.

Since javadoc implementations vary and work differently, you need to examine details such as the version of your Java development system and choose the right Javadoc version.

Instance

Here's a simple example of using instruction comments. Note that each comment is in front of the item it describes.

After javadoc processing, comments for the SquareNum class will be found in .html SquareNum.

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, use the javadoc tool to work with SquareNum.java files:

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

Java document notes

Table of contents