Getting started with Java - advanced tutorial - 09. Documentation notes

Original address: http://www.work100.net/training/java-documentation.html
More tutorials: Beam cloud - free course

Documentation Comments

Serial number Chapter in text video
1 Summary -
2 javadoc tag -
3 Documentation Comments -
4 What does javadoc output -

Please refer to the navigation above for reading

1. overview

Java supports three annotation methods. The first two are / / and / * * /, and the third is called description annotation, which starts with / *, and ends with * /.

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

Note to make it more convenient for you to record your program information.

2.javadoc label

javadoc tool software recognizes 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 Flag an exception thrown by a class @exception exception-name explanation
{@inheritDoc} Comments inherited from direct parent Inherits a comment from the immediate surperclass.
{@link} Insert a link to another topic {@link name text}
{@linkplain} Inserts a link to another topic, but the link displays plain text fonts Inserts an in-line link to another topic.
@param Describes the parameters of a method @param parameter-name explanation
@return Description return value type @return explanation
@see Specify a link to another topic @see anchor
@serial Describe a serialization property @serial description
@serialData Describes the data written through the writeObject() and writeExternal() methods @serialData description
@serialField Describe an ObjectStreamField component @serialField name type description
@since Mark when a specific change is introduced @since release
@throws Same as @ 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 property Displays the value of a constant, which must be a static field.
@version Specifies the version of the class @version info

3. Document notes

After the initial / *, the first line or lines are the main descriptions of classes, variables, and methods.

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

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

The following is an example of an explanatory note for a class:

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

4. What Javadoc output

The javadoc tool takes the source code of your Java program as input and outputs some HTML files containing your program comments.

The information of each class will be in its own HTML file. javadoc can also output the inherited tree structure and index.

Due to the different implementation and work of Javadoc, you need to check the details such as the version of your Java development system and select the appropriate version of Javadoc.

Example

Here's a simple example of using a description annotation. Notice that each comment precedes the item it describes.

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

import java.io.*;

/**
* This class demonstrates document annotations
* @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 process the 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
$

Last article: Applet

If you are interested in the content of the course, you can scan the code to pay attention to our official account or QQ group, and pay attention to our curriculum updates in time.


Tags: Java Asterisk

Posted on Sat, 07 Mar 2020 16:39:13 -0800 by LuaMadman