Java文档注释

Java文档注释（Doc[umentation] Comments ）

注意不要将注解（Annotation）与注释( Comments)混淆。

Java的有三种注释：

（1）单行注释：// 注释内容

（2）多行注释：/* 注释内容 */

（3）文档注释：/** 注释内容 *./ ，Java文档注释(Java Doc Comments)是专门为了用javadoc工具自动生成文档而写的注释，它是一种带有特殊功能的注释。如果编写java源代码时添加了合适的文档注释，然后通过JDK提供的Javadoc工具可以直接将源代码里的文档注释提取成一份系统的API文档。

文档注释与一般注释的最大区别，起始符号是/**，这种注释可以用来自动地生成文档。在JDK中有个javadoc的工具，可以由源文件生成一个HTML文档。使用这种方式注释源文件的内容，显得很专业，并且可以随着源文件的保存而保存起来。也就是说，当修改源文件时，也可能对这个源代码的需求等一些注释性的文字进行修改，那么，这时候可以将源代码和文档一同保存，而不用再另外创建一个文档。

文档注释采用HTML语法规则书写，支持HTML标记(tag)，同时也有一些额外的辅助标记。需要注意的是，这些标记不是给人看的（通常他们的可读性也不好），他们的作用是为了javadoc工具更好地生成最终文档。

 

文档注释位置：

文档注释只负责描述类(class)、接口(interface)、方法(method)、构造器(constructor)、成员字段(field)。并且，文档注释必须写在类、接口、方法、构造器、成员字段前面，而写在其他位置，比如函数内部，是无效的文档注释。

（1）类注释。类注释用于说明整个类的功能、特性等，它应该放在所有的“import”语句之后，在class定义之前。这个规则也适用于接口（interface）注释。

（2）方法注释。方法注释用来说明方法的定义，比如，方法的参数、返回值及说明方法的作用等。方法注释应该放在它所描述的方法定义前面。

（3）属性注释。默认情况下，javadoc只对公有（public）属性和受保护属性（protected）产生文档——通常是静态常量。

（4）包注释。类、方法、属性的注释都直接放到Java的源文件中，而对于包的注释，无法放到Java文件中去，只能通过在包对应的目录中添加一个package.html的文件来达到这个目的。当生成HTML文件时，package.html文件的和部分的内容将会被提取出来当做包的说明。关于包注释，后面还会有更进一步的解释。

（5）概要注释。除了包注释外，还有一种类型的文档无法从Java源文件中提取，就是对所有类文件提供概要说明的文件。同样的，也可以为这类注释单独新建一个HTML文件，这个文件的名字为“overview.html”，它的和标记之间的内容都会被提取。

 

文档注释的标记 (Tag)

以@开头的标签为 Javadoc 标记，由@和标记类型组成，缺一不可。@和标记类型之间有时可以用空格符分隔，但是不推荐用空格符分隔，这样容易出错。

下面是一部分常见标记

@author：作者。

@version：版本。

@docroot：表示产生文档的根路径。

@deprecated：不推荐使用的方法。

@param：方法的参数类型。

@return：方法的返回类型。

@see：用于指定参考的内容。

@exception：抛出的异常。

@throws：抛出的异常，和exception同义

 

下面是一个类注释的例子，一个类注释的创建人、创建时间和描述是不可缺少的：

/**

 * @author: zhangsan

 * @createDate: 2020/12/28

 * @description: this is the student class.

 */

public class student{

    .................

}

 

提示：没有必要在每一行的开始用*。例如，以下注释同样是合法的：

/**

   @author: zhangsan

   @createDate: 2020/12/28

   @description: this is the student class.

 */

public class student{

    .................

}

 

下面是一个方法注释的例子，add() 方法中声明了两个形参，并将它们两个的和作为返回值返回：

/**

 * @param num1: 加数1

 * @param num2: 加数2

 * @return: 两个加数的和

 */

public int add(int num1,int num2) {

    int value = num1 + num2;

    return value;

}

 

为类的构造方法添加注释时，一般声明该方法的参数信息，例如：

public class Student {

   String name;

   int age;

   /**

    * @description: 构造方法

    * @param name: 学生姓名

    * @param age: 学生年龄

    */

   public Student(String name,int age) {

    this.name = name;

    this.age = age;

   }

}

 

下面是一个字段（成员变量）注释的例子，字段注释在定义字段的前面，用来描述字段的含义：

/**

 * 用户名

 */

public String name;

或使用如下格式：

/**用户名*/

public String name;

 

 

下面给出一个简单而完整的实例

在经过 javadoc 处理之后，SquareNum 类的注释将在 SquareNum.html 中找到。

SquareNum.java 文件代码如下：

import java.io.*;

 

/**

* 这个类演示了文档注释

* @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);

   }

}

 

附录、javadoc工具识别以下标记

标签	描述	中文描述
@author	Identifies the author of a class.	标识一个类的作者
@deprecated	Specifies that a class or member is deprecated.	指名一个过期的类或成员
{@docRoot}	Specifies the path to the root directory of the current documentation	指明当前文档根目录的路径
@exception	Identifies an exception thrown by a method.	标志一个类抛出的异常
{@inheritDoc}	Inherits a comment from the immediate superclass.	从直接父类继承的注释
{@link}	Inserts an in-line link to another topic.	插入一个到另一个主题的链接
{@linkplain}	Inserts an in-line link to another topic, but the link is displayed in a plain-text font.	插入一个到另一个主题的链接，但是该链接显示纯文本字体
@param	Documents a method's parameter.	说明一个方法的参数
@return	Documents a method's return value.	说明返回值类型
@see	Specifies a link to another topic.	指定一个到另一个主题的链接
@serial	Documents a default serializable field.	说明一个序列化属性
@serialData	Documents the data written by the writeObject( ) or writeExternal( ) methods	说明通过writeObject( ) 和 writeExternal( )方法写的数据
@serialField	Documents an ObjectStreamField component.	说明一个ObjectStreamField组件
@since	States the release when a specific change was introduced.	标记当引入一个特定的变化时
@throws	Same as @exception.	和 @exception标签一样.
{@value}	Displays the value of a constant, which must be a static field.	显示常量的值，该常量必须是static属性。
@version	Specifies the version of a class.	指定类的版本

 

注解（Annotation）与注释( Comments)的区别
作用不同：注解也叫元数据。是Java 5以后版本引入的一个特性。是Java 编译器可以理解的部分，是给编译器看的。通过标记包、类、字段、方法、局部变量、方法参数等元素据，告诉jvm这些元素据的信息。注释是程序员对源代码做一些记忆或提示性描述，是给人来看的。它能告诉开发者这段代码的逻辑、说明、特点等内容，对代码起到解释、说明的作用。
使用范围不同：注解 ，参与代码编译，以@开头的，与工具一起使用。对于位置、语法、内容有一定的限制。注释 ，可以随意在任务位置填写内容，对代码任何没有影响。
运行过程不同：
注解，在运行中JVM会去读取它，包含多种加载策略，可以灵活配置。并对相应数据进行的操作，会向程序员反遣被标元素的注解。
注释，会被编译器忽略。

更多详情，参见 JavaSE之注释规范、文档注释及注解  https://blog.csdn.net/Hornlet/article/details/80047879