目录： 1. 在代码中使用文档注释2. 类注释3. 方法注释4. 域注释5. 通用注释6. 包与概述注释7. 注释的抽取
1. 在代码中使用文档注释
Java 程序员在开发的过程中，或多或少都会有查阅 API（Application Programming Interface）文档的需求，层次分明的 API 文档给 Java 开发带来了极大的便利。那么，我们有没有办法给自己的程序，也“编写”这样一个结构化的文档呢？答案当然是肯定的！
JDK 包含一个很有用的工具，叫做 javadoc, 它可以由 Java 源文件生成一个HTML文档，只需要在源代码中添加相对应的以 /**开始，并以 */ 结束的注释，然后利用 javadoc 指令，就可以为自己的程序生成类似 Java API 的文档！
这是一种很好的方式，因为这种方式可以将代码与注释保存在一个地方。如果将文档存人一个独立的文件中，就有可能会随着时间的推移，出现代码和注释不一致的问题。然而，如果文档注释与源代码在同一个文件中，在修改源代码的同时，重新运行 javadoc 就可以轻而易举地保持两者的一致性。
编写Java程序时，需为以下部分插入文档注释：
包公有类与接口公有的和受保护的构造器及方法公有的和受保护的域 2. 类注释类注释必须放在 import 语句之后，类定义之前。例如：
import com.帅气的星月.demo.Person;/** * Describe your class * * @version 1.0 2020-11-07 * @author xndhb */public class Student extends Person {} 3. 方法注释每一个方法注释必须放在所描述的方法之前。对于方法而言，还可以使用下面的标记：
@param：对方法的参数变量进行描述。@return：对方法的返回值进行描述。@throws：用于表示这个方法有可能抛出异常。 /*** 一个寻找列表中元素（Integer类型）最大值的方法* @param list 搜索最大值的列表* @return max list中的最大值*/public Integer getMax(List<Integer> list){Integer max = 0;// 方法的具体实现return max;} 4. 域注释只需要对公有域（通常指的是静态常量）建立文档。例如：
/*** The "Hearts" card suit*/public static final int HEARTS = 1; 5. 通用注释@author 姓名
@version 版本
@since 文本
这个标记将产生一个“ since” （始于）条目。这里的 text 可以是对引人特性的版本描 述。例如，©since version 1.7.10
@deprecated 文本
这个标记将对类、方法或变量添加一个不再使用的注释。
@see/@link 引用
通过 @see 和 @link 标记，可以使用超级链接，链接到 javadoc 文档的相关部分或外部文档。
6. 包与概述注释可以直接将类、方法和变量的注释放置在 Java 源文件中，只要用 /** . . . */ 文档注释界定就可以了。但是，要想产生包注释，就需要在每一个包目录中添加一个单独的文件。
可以 有如下两个选择：
提供一个以 package.html 命名的 HTML 文件。在标记<body>...</body> 之间的所有文本都会被抽取出来.提供一个以 package-info.java命名的 Java 文件。这个文件必须包含一个初始的以 /** 和 */ 界定的 Javadoc 注释，跟随在一个包语句之后。它不应该包含更多的代码或注释。还可以为所有的源文件提供一个概述性的注释。这个注释将被放置在一个名为overview.html 的文件中，这个文件位于包含所有源文件的父目录中。标记<body>... </body>间的所有文本将被抽取出来。当用户从导航栏中选择“Overview” 时，就会显示出这些注释内容。 7. 注释的抽取这里，假设 HTML 文件将被存放在目录 docDirectory 下，执行以下步骤：
切换到包含想要生成文档的源文件目录。如果有嵌套的包要生成文档，例如com.horstmann.corejava，就必须切换到包含子目录com的目录（如果存在 overview.html 文件的话，这也是它的所在目录)。如果是一个包，应该运行命令:javadoc -d docDirectory nameOfPackage对于多个包生成文档，运行:
javadoc -d docDirectory nameOfPackage1 nameOfPackage2…如果文件在默认包中，就应该运行：
javadoc -d docDirectory *.java
如果省略了 -d docDirectory 选项，那 HTML 文件就会被提取到当前目录下。这样有可能会带来混乱，因此不提倡这种做法。
在提取文档注释时经常需要指定编码方式，加上 -encoding charset 可以指定编码方式（charset处填写编码方式，如 UTF-8）。例如：
javadoc -d Document -encoding UTF-8 com.帅气的星月.client com.帅气的星月.server com.帅气的星月.view
生成成功之后，在src目录下新增了一个Document文件夹，提取出来的文档就被放在这个文件夹里：
链接：点击此处以下载示例资源
更多需求可以在命令行中输入 javadoc -help 查看，用浏览器打开上述示例中 Document 文件夹下的 index.html 文件，浏览器中会出现如下图所示的内容：
利用 javadoc，就可以为自己的代码生成类似 Java API 的 HTML 文档了，感兴趣的小伙伴不妨也尝试下为自己的程序“编写”一份清晰的说明书吧！