Java文档注释（拓展）

Java文档注释（拓展）

学而不思则罔，思而不学则殆。 ——《论语·为政》

Java的三种注释：
* 单行注释
* 多行注释
* 文档注释

Java文档注释：
使用 /*  */ 将文档注释内容括起来。

文档注释概览

文档注释只负责描述类(class)、接口(interface)、方法(method)、构造器(constructor)、成员字段(field)。

相应地，文档注释必须写在类、接口、方法、构造器、成员字段前面，而写在其他位置，比如函数内部，是无效的文档注释。

例如：

类注释。

类注释用于说明整个类的功能、特性等，它应该放在所有的“import”语句之后，在class定义之前。这个规则也适用于接口注释。

方法注释。

方法注释用来说明方法的定义，比如，方法的参数、返回值及说明方法的作用等。方法注释应该放在它所描述的方法定义前面。

文档注释内容

由描述部分和标记部分组成。

描述部分就是功能介绍、方法解释等的内容；

标记部分前有标记标签，例如@author、@version......

描述部分

描述部分的第一行应该是一句对类、接口、方法等的简单描述，这句话最后会被 javadoc 工具提取并放在索引目录中。

跟在第一个英文句号之后的tab、空行或行终结符规定了第一句的结尾。

除了普通的文本之外，描述部分可以使用：

  1. HTML语法标签，例如 xxx

  2. javadoc规定的特殊标签，例如 {@link xxx} 。

    标签的语法规则是：{@标签名 标签内容}

需要注意的地方：

  1. 标签在有javadoc工具生成文档时会转化成特殊的内容，比如 {@link URL} 标签会被转化成指向URL类的超链接

  2. 如果注释包含多段内容，段与段之间需要用

    分隔，空行是没用的

  3. 为了避免一行过长影响阅读效果，务必将每行的长度限制在80个字符以内

  4. 善用javadoc工具的复制机制避免不必要的注释：

如果一个方法覆盖了父类的方法或实现了接口种的方法，那么javadoc工具会在该注释里添加指向原始方法的链接，此外如果新方法没有注释，那么javadoc会把原始方法的注释复制一份作为其注释，但是如果新方法有注释了，就不会复制了。

标记部分

标记部分跟在描述部分之后，且前面必须有一个空行间隔

所有标签：

标签 描述
@author 标识一个类的作者
@deprecated 指名一个过期的类或成员
{@docRoot} 指明当前文档根目录的路径
@exception 标志一个类抛出的异常
{@inheritDoc} 从直接父类继承的注释
{@link} 插入一个到另一个主题的链接
{@linkplain} 插入一个到另一个主题的链接，但是该链接显示纯文本字体
@param 说明一个方法的参数
@return 说明返回值类型
@see 指定一个到另一个主题的链接
@serial 说明一个序列化属性
@serialData 说明通过writeObject( ) 和 writeExternal( )方法写的数据
@serialField 说明一个ObjectStreamField组件
@since 标记当引入一个特定的变化时
@throws 和 @exception标签一样.
{@value} 显示常量的值，该常量必须是static属性。
@version 指定类的版本（不是Java版本）

常见标签:

  1. @author 作者，没有特殊格式要求，名字或组织名称都可以
  2. @version 软件版本号（注意不是java版本号），没有特殊格式要求
  3. @param 方法参数，格式为： @param 参数名称 参数描述

  • 可以在参数描述中说明参数的类型

  • 可以在参数名称和参数描述之间添加额外的空格来对齐

  • 破折号或其他标点符号不能出现在参数描述之外的地方

  1. @return 方法返回值，格式为： @return 返回值描述 ，如果方法没有返回值就不要写@return

  2. @deprecated 应该告诉用户这个API被哪个新方法替代了，随后用 @see 标记或 {@link} 标记指向新API，比如：

/**
* @deprecated As of JDK 1.1, replaced by
* {@link #setBounds(int,int,int,int)}
*/
  1. @throws （或 @exception ）包含方法显式抛出的检查异常(Checked Exception)，至于非显示抛出的其他异常(Unchecked Exception)，除非特别有必要，否则就别写了。一个原则就是，只记录可控的问题，对于不可控的或不可预测的问题，不要往上面写。
检查异常：在try语法块中触发，在catch块中捕获的异常，这些异常会由编译器在编译阶段检查并强制程序员处理
非检查异常：包括运行时异常(RuntimeException)和错误(Error)。
  1. 自定义标记

注释风格：

  1. 按照如下顺序提供标记
@author（只出现在类和接口的文档中）
@version（只出现在类和接口的文档中）
@param（只出现在方法或构造器的文档中）
@return（只出现在方法中）
@exception（从java1.2之后也可以使用@thrown替代）
@see
@since
@serial（也可以使用@serialField或@serialData替代）
@deprecated

此外，如果有多个相同标记，也要注意顺序：

多个@author标记，应该按照时间顺序排列，即原作者应该排在第一个位置
多个@param标记，应该按照参数定义的顺序排列
多个@exception（或是@thrown）应该按照异常的字母顺序排列
多个@see标记，应该按照注释的逻辑顺序排列，即从最近的到最远的，从最具体的到最一般的
  1. 必须包含的标记
如果方法有参数，@param标记必须包含，而且每个对应一个参数
如果方法有返回值，@return标记必须包含

其他注释

  1. 包级别的文档注释
    从java1.2起允许包级别的文档注释，用以描述包信息。每个包都可以有自己的包文档注释，这些注释被写在叫package.html的单独文件中，并且放至于与源码(*.java)相同的路径下，注意，一定不能单独放置在其他路径。
    javadoc工具按照以下流程处理package.html:
把主要内容复制到最终生成的package-summary.html文件中
处理@see, @since, 或{@link}标记
把第一句话复制到javadoc的索引中

在包注释主要介绍一下这个包大致是做什么用的、背景信息、在使用方面需要注意的地方等等信息

  1. 匿名、内部类的文档注释
    javadoc不会提取内部类的文档注释，所以如果想要在最终生成的文档中包含内部类的信息，方法就是——写在外部类的文档注释里。

文档注释生成文档时中文乱码问题

编写文档注释：

命令行窗口输入javadoc命令生成文档，发现出现以下报错：

原因：

是因为命令行窗口当前的编码为GBK，而文档注释里存在中文，GBK编码不支持中文，从而导致乱码。（右键窗口白色部分点击属性查看命令行窗口编码）

解决方法：只需要在 javadoc 命令后加入参数 -encoding utf-8 -charset utf-8

解释一下上述参数的意思：

-d：生成一个文件夹接受生成的文档文件，后面的 HelloDoc 为文件夹名。

-author、-version：为显示文档的作者和版本，对应文档注释里的@author、@version。

-encoding utf-8 -charset utf-8：则是将该文档注释的编码解码形式修改为utf-8，从而解决中文乱码问题。

通过上述操作，就能看到在Java文件目录下生成一个HelloDoc文件夹。

点击index.html文件就可以看到我们的注释文档。

后记

本文章文档注释内容部分取自文章（ ），有删减。

能力有限，难免有遗漏或错误，如有发现望指正。

相关

标签