Java Learning之文档注释

文档注释的结构

　　文档注释主体的开头是一句话，概述类型或成员的作用，应自成一体。后面可跟其他句子或段落，用以详细说明类、接口、方法或字段。

　　除了这些描述性的段落以外，后也可跟其他段落，数量不限，并且每段以一个特殊的文档注释标签开头，如@author、@param、@returns。这些包含标签的段落提供类、接口、方法或字段的特殊信息，javadoc会以标准形式显示这些信息。

　　文档注释的描述性内容可以包含简单的HTML标记标签，在这里列举几个常用的：

• 　　<i>name</i> 表示强调
• 　　<code>name</code> 用于显示类、方法和字段的名称
• 　　<pre>name</pre> 用于显示多行代码示例
• 　　<p>name</p> 把说明分成多个段落
• 　　<ul><li>name</li><ul> 用于显示无序列表等结构
• 　　如果想引入图片，则需要将图片放在源码目录的doc-files子目录中，且要使用类名和一个整数后缀命名这张图片。如<img src="doc-files/Circle-2.jpg">

　　需要注意的是，由于javadoc提取的文档是个html，因此，为了避免你的文档注释影响所生成的html文件，你的文档注释是不能包含html主结构标签的，例如<h2></h2>以及<hr></hr>。此外，还应该避免使用<a>link</a>标签引入超链接或交叉引用，如果有这方面的需求，应使用特殊的文档注释标签，后续小节将会提及。

文档注释标签

　　@author name

　　　　添加一个“Author：”条目，内容是指定的名字。每个类和接口的定义都应该使用这个标签，但单个方法和字段一定不能使用。如果有多个作者，可如下形式使用多个该标签：

　　　　　　@author Ben Evans

　　　　　　@author Ju Mao  

　　　　要求：多位作者按顺序列出，按照作者的时间顺序，从最初作者开始列，如果作者未知，可用unascribed。

　　@version text

　　　　插入一个“Version：”条目，内容是，指定的文本，如：

　　　　@version 1.32, 18/11/07

　　　　表示类或方法的版本是1.32，在18年11.7号更新。每个类和接口都应该包含这个标签，单个方法和字段不能使用。这个标签经常和支持自动排序版本号的版本控制系统使用。

　　　　如果不指定命令行参数-versio， javadoc不会输出版本信息。

　　@param parameter-name description

　　　　把指定的参数及其说明添加到当前方法的“Parameters：”区域。

　　　　在方法和构造方法的文档注释中，每个参数都要使用一个@param标签列出，而且应该按照参数传入的顺序排列。　　

　　　　这个标签只能出现在方法和构造方法的文档注释中。

　　　　为便于阅读，通常采用如下格式：

　　　　@param o　　要插入对象

　　　　@param index　　插入对象位置

　　@return description

　　　　插入一个“Returns：”区域，内容是指定的说明。

　　　　每个方法都应该使用这个注释标签，除非方法返回值为void，或者是构造方法。

　　　　说明需要多长就写多长，但为了保持简洁，如下使用句子片段：

　　　　@return <code>true</code>:　　成功插入

　　　　　　　　<code>false</code>:　　列表中已经包含要插入的对象

　　@exception full-classname description

　　　　添加一个“Throws：”条目，内容是指定的异常名称和说明。方法和构造方法的文档注释应该为throws子句中的每个已检异常编写一个@exception标签，如：

　　　　@exception java.io.FileNotFoundException

　　　　　　　　　　　　　　 如果找不到指定文件

　　　　如果方法的用户基于某种原因想捕获当前方法抛出的未检异常，@exception标签也可以为这些未检异常编写文档。

　　　　如果方法能抛出多个异常，要在相邻的几行使用多个@exception标签，而且按照异常名称的字母表顺序排列。

　　　　该标签只能出现在方法和构造方法的文档注释中。

　　　　@throws标签是@exception标签的别名。

　　@deprecated explanation

　　　　该标签指明随后的类型或成员弃用了，应该避免使用。

　　　　这个文本应该说明这个类或成员何时开始被弃用，如果可能的话，还应该推荐替代的类或成员，并且添加只想替代类或成员的链接，如：

　　　　@deprecated 从3.0版本开始，这个方法被{@link #setColor}替代了。

　　　　{@link #setColor}标签是java文档注释中，所用的正确的超链接引用格式，后续会说明。

　　@since version

　　　　指明类型或成员何时添加到API中。这个标签后面应该跟着版本号或其他形式的版本。例如：

　　　　@since JNUT 3.0

　　　　每个类型的文档注释都应该包含一个@since标签

　　　　类型版本之后添加的任何成员，都要在其文档注释中加上@since标签

　　@serial description

　　　　类序列化的方式是公开API的一部分。如果类能序列化，就应该在文档注释中，使用这个标签来说明序列化的格式。

　　　　在实现Serializable接口的类中，组成序列化状态的每个字段，都应该在其文档注释中使用该标签

　　　　对于使用默认序列化机制的类来说，除了声明为transient的字段，其他所有字段，包括声明为private的字段，都要在文档中使用该标签。

　　　　description应该简要说明字段及其在序列化对象中的作用。

　　　　在类和包的文档注释中，也可以使用@serial标签，指明是否为当前类或包生成“Serialized Form”界面。句法如下：

　　　　@serial include

　　　　@serial excude

　　@serialField name type description

　　　　实现Serializable接口的类可以声明一个名为serialPersistentFields的字段，定义序列化格式。

　　　　serialPersistentFields字段的值是一个数组，由ObjectStreamField对象组成。

　　　　对这样的类来说，在serialPersistentFields字段的文档注释里，数组中的每个元素都要使用一个@serialField标签列出，每个标签都要指明元素在类序列化状态中的名称、类型和作用。

　　@serialData description

　　　　实现Serializable接口的类可以定义一个writeObject（）方法，用于写入数据，代替默认序列化机制提供的写入方法。

　　　　实现Externalizable接口的类可以定义一个writeExternal（）方法，该方法把对象的完整状态写入序列化流。

　　　　writeObject（）和writeExternal（）方法的文档注释中应该使用@serialData标签，description应该说明这个方法的序列化格式。

 行内文档注释标签

　　在文档注释中，只要能使用html文本的地方，都能使用行内标签。因为这些标签直接出现在html文本流中，所以要花括号把标签中的内容和周围的html文本隔开。

　　{@link reference}

　　　　{@link}标签和@see标签的作用类似，但@see标签是在专门的“See Also：”区域放一个指向引用的链接，而{@link}标签在行内插入链接。

　　　　在文档注释中，只要能使用html文本的地方，都可以使用{@link}标签。

　　　　{@link}标签可以出现在类、接口、方法或字段的第一句话，也能出现在@param、@returns、@exception、@deprecated标签的说明中。

　　　　{@link}标签中的reference使用专门的句法：

• • • 如果reference以引号开头，表示书名或其他出版物的名称，参数值是什么就显示什么
    • 如果reference以<符号开头，表示使用<a>标签标记的任意html超链接，这个超链接会原样插入生成的文档
    • 如果reference既不是引号中的字符串，也不是超链接，那么应该具备如下格式：

　　　　　　　　　　　　feature [label]

　　　　　　　　　此时，javadoc会把label当成超链接的文本，指向feature指定的内容。如果没指定label（一般都不指定），javadoc会使用feature作为超链接的文本。

　　　　　　　　　feature可以指向包、类型或类型的成员，使用下述格式的一种：

• • • • pkgname：指向指定的包

　　　　　　　　　　　　　@see java.lang.reflect

• • • • pkgname.typename：指定完整的包名，指向对应的类、接口、枚举类型或注解类型

　　　　　　　　　　　　@see java.util.List

• • • • typename：不指定包名，指向对应的类型

　　　　　　　　　　　　@see List

　　　　　　　　　　　　javadoc会搜索当前包和typename类导入的所有类，解析这个引用

• • • • typename#methodname：指向指定类型中指定名称对应的方法或构造方法。

　　　　　　　　　　　　　@see java.io.InputStream#reset

　　　　　　　　　　　　　@see InputStream#close

　　　　　　　　　　　　如果类型不包含包名，会按照typename使用的方式解析。如果方法重载了，或类中定义有同名字段，这种句法会引起歧义。

• • • • typename#methodname（paramtypes）：指向指定类型中指定名称对应的方法或构造方法，而且明确指定参数的类型。

　　　　　　　　　　　　　　交叉引用重载的方法时可以使用这种格式，例如：

　　　　　　　　　　　　　　@see InputStream#read（byte[]， int，int）

• • • • #methodname

　　　　　　　　　　　　指向一个没有重载的方法或构造方法，这个方法在当前类或接口中，或者在当前类或接口的某个外层类、超类或超链接中。

　　　　　　　　　　　　这个简短格式用于指向同一个类中的其他方法。例如：

　　　　　　　　　　　　@see #setBackgroundColor

• • • • #methodname（paramtypes）

　　　　　　　　　　　　指向当前类、接口或者某个超类、外层类中的方法或构造方法。这种格式可以指向重载的方法，因为它明确列出方法参数的类型。例如：

　　　　　　　　　　　　@see #setPosition（int，int）

• • • • typename#fieldname：指向指定类中的指定字段

　　　　　　　　　　　　@see java.io.BufferedInputStream#buf

　　　　　　　　　　　　如果类型不包含包名，会按照typename使用的方式解析。

• • • • #fieldname

　　　　　　　　　　　　指向一个字段，这个字段在当前类型中，或者在当前类型的某个外层类、超类或超链接中。例如：

　　　　　　　　　　　　　　@see #x

　　{@linkplain reference}

　　　　{@linkplain}标签和{@link}标签的作用类似，不过，在{@linkplain}标签生成的链接中，链接文字使用的是普通字体，而{@link}标签使用代码字体。

　　　　如果reference包含要链接的feature和指明链接替代文本的label，就要使用{@linkplain}

　　{@inheritDoc}

　　　　如果一个方法覆盖了超类的方法，或者实现了接口中的方法，那么这个方法的文档注释可以省略一些内容，让javadoc自动从被覆盖或被实现的方法中继承。

　　　　{@inheritDoc}标签可以继承单个标签的文本，还能在继承的基础上再添加一些说明。继承单个标签的方式如下所示：

　　　　　　@param index @{inheritDoc}

　　　　　　@return @{inheritDoc}

　　{@docRoot}

　　　　这个行内标签没有参数，javadoc生成文档时会把它替换成文档的根目录。

　　　　这个标签在引用外部文件的超链接中很有用，例如引用图片或者一份版权声明：

　　　　<img src="{@docroot}/images/logo.gif">

　　　　这份资料受<a href="{@docroot}/legal.html">版权保护</a>

　　{@literal text}

　　　　这个行内标签按照字面形式显示text，text中的所有html都会转义，而且所有javadoc标签都会被忽略。

　　　　虽然不保留空白格式，但仍适合在<pre>标签中使用。

　　{@code text}

　　　　这个标签和{@literal}标签的作用类似，但会使用代码字体显示text的字面量。等价于：

　　　　&lt;code&gt;{@literal <replaceable>text</replaceable>}&lt;/code&gt;

　　{@value}

　　　　没有参数的{@value}标签在static final字段的文档注释中使用，会被替换成当前字段的常量值。

　　{@value reference}

　　　　这种{@value}标签的变体有一个reference参数，指向一个static final字段，会被替换成指定字段的常量值。