12.JavaDoc

JavaDoc

JavaDoc是Java提供的一种工具，它能够从源代码中的特殊注释里提取信息，进而自动生成API文档。

1. 基本语法

JavaDoc注释以/**开头，以*/结尾，可置于类、方法或字段的声明之前。

/**
 * @author wsp
 * @version 1.0
 * @since 1.8
 */
public class Example {
    /** 这是一个成员变量的注释 */
    private String name;

    /**
     * 构造函数
     * @param name 初始化名称
     */
    public Example(String name) {
        this.name = name;
    }

    /**
     * @return 返回name属性  //输入`/**`后回车，会自动生成这行参数，但注意，如果在this。name = name前写`/**`后回车不会生成该行。成员变量是类的属性（如 private String name），它不是方法的输入参 
                               数，因此不存在 “参数” 需要注释。IDE 会根据语法规则判断当前注释的位置：若注释在方法上方：IDE 会识别出方法的参数列表，并提示生成 @param 标签（如构造函数 
                               Example(String name) 的注释）。若注释在成员变量上方：IDE 知道这是字段注释，不会触发 @param 标签的生成。
     */
    public String getName() {
        return name;
    }
}

2. 常用标签

• 类注释标签

  • @author：标注作者信息。
  • @version：说明版本情况。
  • @since：表明从哪个版本开始引入。
  • @see：用于引用其他类或方法。

• 方法注释标签

  • @param：对方法参数进行说明。
  • @return：阐述方法的返回值。
  • @throws：指出方法可能抛出的异常。
  • @deprecated：标记方法已过时。

3. 生成文档

要生成文档，可使用以下命令：

javadoc -d doc -author -version Example.java

其中，参数的含义如下：

• -d doc：指定文档的输出目录为doc。
• -author：在文档中显示作者信息。
• -version：在文档中显示版本信息。

4. 高级特性

• HTML标签的使用：在注释中可以使用HTML标签，像<p>、<ul>等。

  /**
   * 这个方法会执行以下操作：
   * <ol>
   *   <li>处理输入数据</li>
   *   <li>返回处理结果</li>
   * </ol>
   */
  

• 包级注释：可以在package-info.java文件中添加包的注释。

  /**
   * 这个包包含了项目的核心功能类。
   */
  package com.example.core;
  

5. 生成javadoc

1.使用命令行，在对应类的文件夹导航栏输入cmd，弹出命令行，输入：javadoc -encoding UTF-8 -charset UTF-8 Doc.java
2.在IDEA中，tools→Generate JavaDoc。