文档注释？author、version...

        之前一直看到代码最开始会有一些作者、日期、版本的注释，以为和多行注释一样，但是这其实不是多行注释，而叫做文档注释。还有类/函数前面的那段注释也是文档注释。为什么使用文档注释呢？文档注释可以被特定工具/程序解析直接生成代码的说明文档。

1. 文档注释的定义

        文档注释是用于描述代码中类、接口、方法、构造器和成员属性的一段文本。这些注释可以被特定的工具解析，并用于生成程序的说明文档。比如大家在一些库的官方文档中看到的源代码说明可能就是这样生成的。

2. Javadoc 的作用

        Javadoc 是 Sun Microsystems（现为 Oracle Corporation）提供的一项技术，它能够从 Java 程序的源代码中提取类、方法、成员等注释，并生成与源代码配套的 API 帮助文档。简而言之，Javadoc 用于创建代码的文档，使得其他开发者能够更容易地理解和使用这些代码。也就是上面所说的解析工具。

3. Javadoc 的使用

        要使用 Javadoc，开发者需要在编写程序时按照一套特定的标签进行注释。完成程序编写后，通过运行 Javadoc 命令，可以生成 API 文档。Javadoc 命令的常见使用方式包括：

• javadoc 源文件名.java：生成指定源文件的 API 文档。
• javadoc -d 文档存放目录 源文件名.java：指定生成的文档存放目录。

4. Javadoc 注释规范

        Javadoc 注释通常分为三个部分：

• 概要描述：简要描述类或方法的作用。
• 详细描述：详细描述类或方法的功能和用法。
• 文档标注：包括作者、创建时间、参阅类等信息。

        此外，Javadoc 注释中可以使用一些特定的标记，如 @author、@version、@since、@see、@link、@code、@param、@return、@exception、@throws 等，用于提供更多关于代码的信息。

5. 示例

        以下是一个简单的 Javadoc 注释示例：

/**
 * @author miaomiao
 * @version 1.0
 */

/**
 * return: Null
 * xxxx
 * xxxx
 */
public class JavaDocComment {
    public static void main(String[] args) {
        System.out.println("原来这种注释方式叫文档注释啊~");
    }
}

        通过上述方式，Javadoc 工具可以生成一个 HTML 格式的文档，其中包含了类的详细信息，便于其他开发者阅读和使用。