java 文档注释 -- javadoc 标签

目录

• 1. 文档注释
  • 1.1 文档格式
  • 1.2 Javadoc标签
• 2. 例子
• 3 生成文档
  • 3.1 使用javadoc生成文档
  • 3.2 通过IDEA生成Javadoc

1. 文档注释

Java 文档注释(Java Doc Comments)是专门为了用javadoc工具自动生成文档而写的注释，文档注释与一般注释的最大区别在于起始符号是/**而不是/*或//。

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

文档注释采用HTML语法规则书写，支持HTML标记(tag)，同时也有一些额外的辅助标记。需要注意的是，这些标记不是给人看的（通常他们的可读性也不好），可以通过 Javadoc 命令把文档注释中的内容生成文档，并输出到 HTML 文件中

1.1 文档格式

在类上的文档标注一般分为三段：

第一段：概要描述，通常用一句或者一段话简要描述该类的作用，以英文句号作为结束

第二段：详细描述，通常用一段或者多段话来详细描述该类的作用，一般每段话都以英文句号作为结束

第三段：文档标注，用于标注作者、创建时间、参阅类等信息

生成文档是HTML格式。

换行<br>

分段<p>(写在段前）)

1.2 Javadoc标签

Javadoc 工具可以识别文档注释中的一些特殊标签，这些标签一般以@开头，后跟一个指定的名字，有的也以{@开头，以}结束。Javadoc 可以识别的标签如下表所示：

标签	描述	标签类型
@author	作者标识	包、 类、接口
@deprecated	标识当前API已经过期，仅为了保证兼容性依然存在，以此告之开发者不应再用这个API	包、类、接口、值域、构造函数、 方法
	指明当前文档根目录的路径
@exception	标志一个类抛出的异常	构造函数、 方法
	从直接父类继承的注释
	链接到某个特定的成员对应的文档中	包、类、接口、值域、构造函数、 方法
	插入一个到另一个主题的链接，但是该链接显示纯文本字体	包、类、接口、值域、构造函数、 方法
@param	方法的入参名及描述信息，如入参有特别要求，可在此注释	构造函数、方法
@return	对函数返回值的注释	方法
@see	引用,查看相关内容，如类、方法、变量等	包、类、接口、值域、构造函数、 方法
@serial	说明一个序列化属性
@serialData	说明通过writeObject( ) 和 writeExternal( )方法写的数据
@serialField	说明一个ObjectStreamField组件	@
@since	描述文本,API在什么程序的什么版本后开发支持	包、类、接口、值域、构造函数、 方法
@throws	构造函数或方法所会抛出的异常	构造函数、 方法
	显示常量的值，该常量必须是static属性	静态值域
@version	版本号	包、 类、接口
对两种标签格式的说明：

• @tag 格式的标签（不被{ }包围的标签）为块标签，只能在主要描述（类注释中对该类的详细说明为主要描述）后面的标签部分（如果块标签放在主要描述的前面，则生成 API 帮助文档时会检测不到主要描述）。

• {@tag} 格式的标签（由{ }包围的标签）为内联标签，可以放在主要描述中的任何位置或块标签的注释中。

Javadoc 标签注意事项：

• Javadoc 标签必须从一行的开头开始，否则将被视为普通文本。

• 一般具有相同名称的标签放在一起。

• Javadoc 标签区分大小写，代码中对于大小写错误的标签不会发生编译错误，但是在生成 API 帮助文档时会检测不到该注释内容。

2. 例子

文档注释可以在自己的 IDE 上定义成模板，这样每次通过快捷键就可自动帮你输出在代码中，节省时间，也使代码规范。

文件注释：

/*
 * <p>项目名称: ${project_name} </p> 
 * <p>文件名称: ${file_name} </p> 
 * <p>描述: [类型描述] </p>
 * <p>创建时间: ${date} </p>
 * @author：<a href="mail to: *******@******.com" rel="nofollow">作者</a>
 * @version：
 * @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] [更改人姓名][变更描述]     
 */

3 生成文档

3.1 使用javadoc生成文档

Javadoc 是 Sun 公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释,然后形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的 API 帮助文档。

API 帮助文档相当于产品说明书，而说明书只需要介绍那些供用户使用的部分，所以 Javadoc 默认只提取 public、protected 修饰的部分。如果要提取 private 修饰的部分，需要使用 -private。

如果是第一次使用javadoc命令，可以通过javadoc -help命令查看javadoc使用说明。

例:

javadoc -d 文档存放目录 -author -version 源文件名.java

这条命令编译一个名为"源文件名.java"的 java 源文件，并将生成的文档存放在"文档存放目录"指定的目录下，生成的文档中 index.html 就是文档的首页。-author 和 -version 两个选项可以省略

Javadoc 并不是将代码中的文档注释直接复制到帮助文档的 HTML 文件中，而是读取每一行后，删除前面的号及以前的空格再输入到 HTML 文档。注释前面的号允许连续使用多个，其效果和使用一个号一样，但多个前不能有其他字符分隔，否则分隔符及后面的号都将作为文档的内容。

3.2 通过IDEA生成Javadoc

菜单：Tools -> Generate JavaDoc
注意要配置编码，如果不配置则生成的JavaDoc会乱码，还需要配置Output directory

这里有几点要特别注意一下：

• 注意生成 JavaDoc 的源代码对象的选择，一般以模块（Module）为主，必要时可以单独选择必要的 Java 源代码文件，不推荐以 Project 为 JavaDoc 生成的源范围。
• 里面有一个 Locale 可选填项，表示的是需要生成的 JavaDoc 以何种语言版本展示，根据 javadoc.exe 的帮助说明，这其实对应的就是 javadoc.exe 的 -locale 参数，如果不填，默认可能是英文或者是当前操作系统的语言，既然是国人，建议在此填写 zh_CN，这样生成的 JavaDoc 就是中文版本的，当然指的是 JavaDoc 的框架中各种通用的固定显示区域都是中文的。你自己编写的注释转换的内容还是根据你注释的内容来。
• 还有一个“Other command line arguments:”可选填项，非常重要，是填写直接向 javadoc.exe 传递的参数内容。因为有一些重要的设置，只能通过直接参数形式向 javadoc.exe 传递。例如：
  ``
  -encoding UTF-8 -charset UTF-8 -windowtitle "" -link https://

  - 第一个参数 -encoding UTF-8 表示你的源代码（含有符合 JavaDoc 标准的注释）是基于 UTF-8 编码的，以免处理过程中出现中文等非英语字符乱码；
  - 第二个参数 -charset UTF-8 表示在处理并生成 JavaDoc 超文本时使用的字符集也是以 UTF-8 为编码；
  - 第三个参数 -windowtitle 表示生成的 JavaDoc 超文本在浏览器中打开时，浏览器窗口标题栏显示的文字内容；
  - 第四个参数 -link 很重要，它表示你生成的 JavaDoc 中涉及到很多对其他外部 Java 类的引用，是使用全限定名称还是带有超链接的短名称，举个例子，我创建了一个方法 public void func(String arg)，这个方法在生成 JavaDoc 时如果不指定 -link 参数，则 JavaDoc 中对该方法的表述就会自动变为 public void func(java.lang.String arg)，因为 String 这个类对我自己实现的类来讲就是外部引用的类，虽然它是 Java 标准库的类。如果指定了 -link https://docs.oracle.com/javase/8/docs/api/ 参数，则 javadoc.exe 在生成 JavaDoc 时，会使用 String 这样的短名称而非全限定名称 java.lang.String，同时自动为 String 短名称生成一个超链接，指向官方 JavaSE 标准文档 https://docs.oracle.com/javase/8/docs/api/ 中对 String 类的详细文档地址。-link 实质上是告诉 javadoc.exe 根据提供的外部引用类的 JavaDoc 地址去找一个叫 package-list 的文本文件，在这个文本文件中包含了所有外部引用类的全限定名称，因此生成的新 JavaDoc 不必使用外部引用类的全限定名，只需要使用短名称，同时可以自动创建指向其外部引用 JavaDoc 中的详细文档超链接。每个 JavaDoc 都会在根目录下有一个 package-list 文件，包括我们自己生成的 JavaDoc。


#4. 阿里巴巴《Java 开发手册-嵩山版》注释规约（版权归阿里巴巴《Java 开发手册-嵩山版》所有）
1. 【强制】类、类属性、类方法的注释必须使用 Javadoc 规范，使用/**内容*/格式，不得使用// xxx 方式。

说明：在 IDE 编辑窗口中，Javadoc 方式会提示相关注释，生成 Javadoc 可以正确输出相应注释；在 IDE 中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。

2. 【强制】所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。

说明：对子类的实现要求，或者调用注意事项，请一并说明。

3. 【强制】所有的类都必须添加创建者和创建日期。

说明：在设置模板时，注意 IDEA 的@author 为`${USER}`，而 eclipse 的@author 为`${user}`，大小写有区别，而日期的设置统一为 yyyy/MM/dd 的格式。

 正例：

/**

• @author yangguanbao
• @date 2016/10/31
  */

4. 【强制】方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。

5. 【强制】所有的枚举类型字段必须要有注释，说明每个数据项的用途。

6. 【推荐】与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。

反例：“TCP 连接超时”解释成“传输控制协议连接超时”，理解反而费脑筋。

7. 【推荐】代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。

说明：代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去了导航的意义。

8. 【推荐】在类中删除未使用的任何字段、方法、内部类；在方法中删除未使用的任何参数声明与内部变量。

9. 【参考】谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除。

说明：代码被注释掉有两种可能性：1）后续会恢复此段代码逻辑。2）永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉即可，假如需要查阅历史代码，登录代码仓库即可。

10.【参考】对于注释的要求：第一、能够准确反映设计思想和代码逻辑；第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。

11.【参考】好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释又是相当大的负担。

反例：

// put elephant into fridge
put(elephant, fridge);

方法名 put，加上两个有意义的变量名 elephant 和 fridge，已经说明了这是在干什么，语义清晰的代码不需要额外的注释。
12.【参考】特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描，经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。

1） 待办事宜（TODO）:（标记人，标记时间，[预计处理时间]）

表示需要实现，但目前还未实现的功能。这实际上是一个 Javadoc 的标签，目前的 Javadoc 还没有实现，但已经被广泛使用。只能应用于类，接口和方法（因为它是一个 Javadoc 标签）。

2） 错误，不能工作（FIXME）:（标记人，标记时间，[预计处理时间]）在注释中用 FIXME 标记某代码是错误的，而且不能工作，需要及时纠正的情况。