【Java基础】JavaDoc注释标签大全

亦凉 2023-01-19 08:30 4阅读 0赞

### 文章目录 ###

*   *   *  一.Java注释方式
         *  二.JavaDoc注释用法
         *  三.JavaDoc注释会输出什么
         *  四.JavaDoc注释常用标签
         *   *  1.@see
             *  2.\{@link\}
             *  3.其他JavaDoc标签
             *  4.文档注释模板

### 一.Java注释方式 ###

**Java 支持三种注释方式。分别是**

1.  单号注释 //
2.  多行注释 /\* \*/
3.  文档注释，它以 /\*\* 开始，以 \*/结束。
    
    > 可以使用 javadoc 工具软件来生成信息，并输出到HTML文件中。

### 二.JavaDoc注释用法 ###

在开始的 `/**`之后，第一行或几行是`关于类、变量和方法的主要描述`。之后，你可以包`含一个或多个各种各样的 @ 标签`。`每一个 @ 标签必须在一个新行的开始或者在一行的开始紧跟星号(*).`

*  多个相同类型的标签应该放成一组。例如，如果你有三个 @see 标签，可以将它们一个接一个的放在一起。

下面是一个类的说明注释的实例：

/*** 这个类绘制一个条形图 * @author runoob * @version 1.2 */

### 三.JavaDoc注释会输出什么 ###

javadoc 工具将你 Java 程序的源代码作为输入，输出一些包含你程序注释的HTML文件。

每一个类的信息将在独自的HTML文件里。javadoc 也可以输出继承的树形结构和索引。

由于 javadoc 的实现不同，工作也可能不同，你需要检查你的 Java 开发系统的版本等细节，选择合适的 Javadoc 版本。

### 四.JavaDoc注释常用标签 ###

#### 1.@see ####

*  **使用@see时应注意 写在每行注释的开头。**
 *  **用法：@see 类\#属性 / 方法**

/** * @see ClassA#属性 * @see ClassA#方法 * @see com.joh.demo.ClassB#方法 */

**JavaDoc注解中的`{@link}与@see`，他可以链接类或者方法，方便自己或别人看的时候，可以直接找到你关联的代码类或者啥的。**

> 在编辑器中，按住`ctrl+鼠标左键`，就能直接跳转

#### 2.\{@link\} ####

*  **\{@link\}的使用与@see有一点区别就是可以写在注释的任意位置**
 *  **用法：\{@link 类\#属性 / 方法\}**

/** * {@link ClassA#属性} * {@link ClassA#方法} * {@link com.joh.demo.ClassB#方法} * * 可不用开头写 {@link ClassA#属性} * 可不用开头写 {@link ClassA#方法} * 可不用开头写 {@link com.joh.demo.ClassB#方法} */

**JavaDoc注解中的`{@link}与@see`，他可以链接类或者方法，方便自己或别人看的时候，可以直接找到你关联的代码类或者啥的。**

> 在编辑器中，按住`ctrl+鼠标左键`，就能直接跳转

#### 3.其他JavaDoc标签 ####

<table> 
 <thead> 
  <tr> 
   <th>标签</th> 
   <th>描述</th> 
   <th>示例</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@author</td> 
   <td>标识一个类的作者</td> 
   <td>@author description</td> 
  </tr> 
  <tr> 
   <td>@deprecated</td> 
   <td>指名一个过期的类或成员</td> 
   <td>@deprecated description</td> 
  </tr> 
  <tr> 
   <td>{@docRoot}</td> 
   <td>指明当前文档根目录的路径</td> 
   <td>Directory Path</td> 
  </tr> 
  <tr> 
   <td>@exception</td> 
   <td>标志一个类抛出的异常</td> 
   <td>@exception exception-name explanation</td> 
  </tr> 
  <tr> 
   <td>{@inheritDoc}</td> 
   <td>从直接父类继承的注释</td> 
   <td>Inherits a comment from the immediate surperclass.</td> 
  </tr> 
  <tr> 
   <td>{@link}</td> 
   <td>插入一个到另一个方法或者代码的链接，但是该链接显示链接样式</td> 
   <td><a rel="nofollow">Inserts an in-line link to another topic.</a></td> 
  </tr> 
  <tr> 
   <td>{@linkplain}</td> 
   <td>插入一个到另一个方法或者代码的链接，但是该链接显示纯文本字体</td> 
   <td>Inserts an in-line link to another topic.</td> 
  </tr> 
  <tr> 
   <td>@param</td> 
   <td>说明一个方法的参数</td> 
   <td>@param parameter-name explanation</td> 
  </tr> 
  <tr> 
   <td>@return</td> 
   <td>说明返回值类型</td> 
   <td>@return explanation</td> 
  </tr> 
  <tr> 
   <td>@serial</td> 
   <td>说明一个序列化属性</td> 
   <td>@serial description</td> 
  </tr> 
  <tr> 
   <td>@serialData</td> 
   <td>说明通过writeObject( ) 和 writeExternal( )方法写的数据</td> 
   <td>@serialData description</td> 
  </tr> 
  <tr> 
   <td>@serialField</td> 
   <td>说明一个ObjectStreamField组件</td> 
   <td>@serialField name type description</td> 
  </tr> 
  <tr> 
   <td>@throws</td> 
   <td>和 @exception标签一样.，说明要抛出的异常</td> 
   <td>@throws tag has the same meaning as the @exception tag.</td> 
  </tr> 
  <tr> 
   <td>{@value}</td> 
   <td>显示常量的值，该常量必须是static属性。</td> 
   <td>Displays the value of a constant, which must be a static field.</td> 
  </tr> 
  <tr> 
   <td>@version</td> 
   <td>指定类的版本</td> 
   <td>@version info</td> 
  </tr> 
 </tbody> 
</table>

实例代码

/** * 这个类演示了文档注释 * @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);
       }
    }

#### 4.文档注释模板 ####

类注释

/* * <p>项目名称: ${project_name} </p> * <p>文件名称: ${file_name} </p> * <p>描述: [类型描述] </p> * <p>创建时间: ${date} </p> * <p>公司信息: ************公司 *********部</p> * @author <a href="mail to: *******@******.com" rel="nofollow">作者</a> * @version v1.0 * @update [序号][日期YYYY-MM-DD] [更改人姓名][变更描述] */

方法注释

/** * @Title：${enclosing_method} * @Description: [功能描述] * @Param: ${tags} * @Return: ${return_type} * @author <a href="mail to: *******@******.com" rel="nofollow">作者</a> * @CreateDate: ${date} ${time}</p> * @update: [序号][日期YYYY-MM-DD] [更改人姓名][变更描述] */

getter 和 setter方法注释

/** * 获取 ${bare_field_name} */
    
    
    
    /** * 设置 ${bare_field_name} * (${param})${field} */

参考

> [Java文档注释用法+JavaDoc的使用详解][Java_JavaDoc]

[Java_JavaDoc]: https://blog.csdn.net/lsy0903/article/details/89893934