java文档注释规范：javadoc标签（二）

最新推荐文章于 2024-09-10 20:52:22 发布

huangsiqian

最新推荐文章于 2024-09-10 20:52:22 发布

阅读量1.2w

点赞数 5

分类专栏： javadoc

本文链接：https://blog.csdn.net/huangsiqian/article/details/82818211

版权

javadoc 专栏收录该内容

2 篇文章 1 订阅

订阅专栏

javadoc标签必须从一行的开头（在任何前导空格和可选的星号之后）开始，否则将被视为普通文本。按照惯例，具有相同名称的标签被组合在一起（标签大小写敏感）。例如，将所有@see标记放在一起。标签可以分为：

块标签：只能放在主要描述部分后面的标签部分。块标签的格式为：@tag。
内联标记：可以放在主要描述中的任何位置或块标签的注释中。内联标记用花括号标记：{@ tag}。

现有的javadoc标签（截至jdk1.5）：

Tag Introduced in JDK/SDK
@author 1.0
{@code} 1.5
{@docRoot} 1.3
@deprecated 1.0
@exception 1.0
{@inheritDoc} 1.4
{@link} 1.2
{@linkplain} 1.4
{@literal} 1.5
@param 1.0
@return 1.0
@see 1.0
@serial 1.2
@serialData 1.2
@serialField 1.2
@since 1.1
@throws 1.2
{@value} 1.4
@version 1.0

@author 名字（文本）
当使用-author选项时，以指定的名字（文本）添加一个“Author”条目到生成的文档中。文档注释可以包含多个@author标签。可以为每个@author标签指定一个名字，或为每个标签指定多个名字。在前一种情况下，Javadoc工具在名字之间插入逗号（，）和空格。在后一种情况下，只需将整个文本复制到生成的文档而不进行解析。因此，如果想要使用除逗号之外的其他分隔符，则可以每行指定多个名字。

@deprecated 被弃用文本
注意：从JDK 5.0开始，可以使用@Deprecated注解来标记弃用程序元素。
添加一个标记此API不应再使用的注释（即使它可能仍然有效）。Javadoc工具把被弃用文本移动到主要描述之前，将其置为斜体字，并在其前面加上一个粗体警告：“Deprecated”。此标签在所有文档注释中都有效：概述，包，类，接口，构造函数，方法和字段。
被弃用文本的第一句应该至少告诉用户API自何时被弃用以及使用什么作为替代。 Javadoc工具只将第一个句子复制到摘要部分和索引。后续句子也可以解释为什么它已被弃用。您应该包含指向替换的API的{@link}标记（对于Javadoc 1.2或更高版本）。

对于Javadoc 1.2及更高版本，请使用{@link}标记。这会在您想要的位置创建内联链接。例如：

/**
 * @deprecated自JDK 1.1起，替换为{@link #setBounds（int，int，int，int）}
 */

对于Javadoc 1.1，标准格式是为每个@deprecated标签创建一个@see标签（但是不能“内联”）。

{@code 文本}

等同于<code> {@ literal} </ code>。
以代码字体显示文本而不将文本解释为HTML标签或嵌套的javadoc标签。这使您可以在文档注释中使用尖括号（<和>）而不是HTML实体（＆lt;和＆gt;），例如参数类型（<Object>），不等式（3 <4）或箭头（ < - ）。例如，doc注释文本：

{@code A C}
在生成的HTML页面中的显示不变：
A C
不会被解释为粗体，并且以代码字体显示。
如果您想要非代码字体的同样的功能，请使用{@literal}标签。

{@docRoot}
表示从任何生成的页面到生成的文档（目标）根目录的相对路径。当您想要包含一个要在所有生成的页面中都引用的文件（例如版权页面或公司徽标）时，它非常有用。在每页底部都链接到版权页面很常见。
{@docRoot}标签可以在命令行和文档注释中使用，在所有文档注释中都有效：概述，包，类，接口，构造函数，方法和字段，包括任何标签的文本部分（例如@return，@param和@deprecated）。

在命令行上，在定义页眉/页脚/底部的地方：

javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'
注意：在make文件中以这种方式使用{@docRoot}时，某些makefile程序需要对括号{}字符进行特殊的转义。例如，在Windows上运行的Inprise MAKE 5.2版需要双括号：{{@ docRoot}}。它还需要双引号（而不是单引号）将诸如-bottom之类的选项的参数括起来（同时省略了href参数周围的引号）。
在文档注释中：

 /**
  * See the <a href="{@docRoot}/copyright.html">Copyright</a>.
  */

需要此标签的原因是由于生成的文档位于分层的目录中，与子包的数量一样深。这个表达式：
<a href="{@docRoot}/copyright.html">
在java/lang/Object.java文件中会解析为：<a href="../../copyright.html">；在java/lang/ref/Reference.java文件中会解析为：<a href="../../../copyright.html">

@exception 类名描述
@exception标签是@throws的同义词。

{@inheritDoc}
从“最近的”可继承类或可实现的接口继承（复制）注释文档到当前doc注释中（位于此标签所在位置）。这允许您在继承树的更高处编写更一般的注释，也使您可以在复制的文本周围编写注释。此标签仅在文档注释中的以下位置有效：

在方法的主要描述块中。在这种情况下，主要描述从继承层次结构中的类或接口复制。
在方法的@return，@param和@throws标签的文本参数中。在这种情况下，标签文本将从继承层次结构中的相应标签复制

请注意，如果缺少此标记，则根据该部分中描述的规则决定是否自动继承注释。

{@link package.class＃member label}
插入带有可见文本标签的内嵌链接（该链接指向引用类的指定包名，类名或成员名的文档）。此标签在所有文档注释中都有效：概述，包，类，接口，构造函数，方法和字段，包括任何标签的文本部分（例如@return，@ param和@deprecated）。
此标签与@see非常相似：两者都需要相同的引用，并且对package.class #member和label接受完全相同的语法。主要区别在于{@link}生成了一个内联链接而不是将链接放在“See Also”部分。如果你需要用在label中使用“}”，请使用 HTML实体标记}，}句子中允许的{@link}标签数量没有限制。例如，这是一个引用getComponentAt（int，int）方法的注释：

Use the {@link #getComponentAt(int, int) getComponentAt} method.

由此，标准doclet将生成以下HTML（假设它引用同一包中的另一个类）：

Use the <a href="Component.html#getComponentAt(int, int)">getComponentAt</a> method.

它在网页上显示为：Use the getComponentAt method。您可以使用-link选项扩展{@link}以链接到没有被文档记录（documented）的类。

{@linkplain package.class＃member label}
与{@link}相同，但链接的label以纯文本显示，而不是代码字体。label是纯文本时很有用。例：
Refer to {@linkplain add() the overridden method}.
这将显示为：
Refer to the overridden method.

{@literal 文本}

显示文本而不将文本解释为HTML标签或嵌套的javadoc标签。这使您可以在文档注释中使用尖括号（<和>）
而不是HTML实体（＆lt;和＆gt;），比如参数类型（<Object>），不等式（3 <4）或箭头（ < - ）。例如，文档注释文本：
{@literal A C}
在浏览器中生成的HTML页面中显示不变： A C。如果您想要相同的功能但使用代码字体的文本，请使用{@code}。

@param 参数名描述
添加一个有指定参数名的“参数”。参数名后紧跟对参数部分的具体描述。描述可以跨多行。此标记仅在方法，构造函数或类的文档注释中有效。
参数名可以是方法或构造函数中的参数名，也可以是类，方法或构造函数的类型参数名。在此参数名周围使用尖括号指定使用类型参数。

类的类型参数示例：

 /**
  * @param <E> Type of element stored in a list
  */
 public interface List<E> extends Collection<E> {
 }

方法的类型参数实例：



     /**
      * @param string  the string to be converted
      * @param type    the type to convert the string to
      * @param <T>     the type of the element
      * @param <V>     the value of the element
      */
     <T, V extends T> V convert(String string, Class<T> type) {
     }

@return 描述
添加带有描述文本的“Returns”部分。该文本应描述返回类型和允许的值范围。此标记仅在方法的文档注释中有效。

@see 引用
添加“See Also”标题，其中包含指向引用的链接或文本条目。文档注释可以包含任意数量的@see标签，这些标签都被归入同一标题下。 @see标签有三种变体，下面的第三种形式是最常见的。此标记在任何文档注释中都有效：概述，包，类，接口，构造函数，方法或字段。要将句子中的内嵌链接插入包，类或成员，请参阅{@link}。

@see "字符串"

添加字符串的文本条目（不会生成链接）。该字符串是书籍或其他（URL不可用的）信息的引用。 Javadoc工具通过查找双引号（"）作为第一个字符来区分此情况。例如：
@see "Java编程语言"
这会生成以下文本：

See Also:
"The Java Programming Language"

@see <a href="URL#value">标签</a>

添加URL＃value定义的链接。 URL＃值是相对或绝对URL。 Javadoc工具通过查找小于号（<）作为第一个字符来区别于其他情况。例如：
@see <a href="spec.html#section"> Java Spec </a>
这会生成一个链接：
See Also:
Java Spec

@see package.class＃member label

添加带有可见文本标签的链接，该链接指向所引用的Java Language中指定的name的文档。label是可选的。如果省略，则name（package.class＃member 部分）作为可见文本显示，并将适当的缩短（请参阅下面：名字如何显示）。使用-noqualifier将全局地从可见文本中删除包名。如果希望可见文本与自动生成的可见文本不同，请使用label。
仅在版本1.2中，只有名字而不是label会自动出现在<code> HTML标签中；从1.2.2开始，<code>始终包含在可见文本周围，无论是否使用label。package.class #member是被引用的任何有效程序元素名：包，类，接口，构造函数，方法或字段名，成员名前面的字符应该是哈希字符（＃）。该class 表示任何顶级或嵌套类或接口。该member表示任何构造函数，方法或字段（包括嵌套类或接口）。如果此名位于被文档记录（documented）的类中，则Javadoc工具将自动创建指向它的链接。要创建指向外部引用类的链接，请使用-link选项。使用其他两个@see的变体中来引用不属于引用类name的文档。（下面的“定制名字”中下更详尽地描述了该参数。）

label是可选文本，作为链接的标签显示。label可以包含空格。空格是package.class #member和label之间的分隔符（不包括括号内的空格，因此可以在方法中的参数之间使用空格）。示例：

/**
 * @see String#equals(Object) equals
 */

标准doclet将生成这样的HTML：

<dl>
<dt><b>See Also:</b>
<dd><a href="../../java/lang/String#equals(java.lang.Object)"><code>equals<code></a>
</dl>

在浏览器中看起来像这样，label是可见的链接文本：
See Also:
equals

定制名字

这里的package.class#member （名字）可以是完全限定的，例如 java.lang.String#toUpperCase() ，也可以不是，例如String#toUpperCase()或#toUpperCase()。如果没有完全限定，Javadoc工具使用普通的Java编译器搜索顺序来查找它，下面在@see的搜索顺序中将详尽描述。名字可以在括号内包含空格（例如方法参数之间）。

当然，提供更短的“部分限定”名字的优点是它们的类型更短，使得源代码中的杂乱程度更低。下表显示了名称的不同形式，其中Class可以是类或接口，Type可以是类，接口，数组或基本类型，方法可以是方法或构造函数。

Typical forms for `@see` package.class#member
Referencing a member of the current class `@see` `#`field `@see` `#`method(Type, Type,...) `@see` `#`method(Type argname, Type argname,...) `@see` `#`constructor(Type, Type,...) `@see` `#`constructor(Type argname, Type argname,...) Referencing another class in the current or imported packages `@see` Class`#`field `@see` Class`#`method(Type, Type,...) `@see` Class`#`method(Type argname, Type argname,...) `@see` Class`#`constructor(Type, Type,...) `@see` Class`#`constructor(Type argname, Type argname,...) `@see` Class.NestedClass `@see` Class Referencing an element in another package (fully qualified) `@see` package.Class`#`field `@see` package.Class`#`method(Type, Type,...) `@see` package.Class`#`method(Type argname, Type argname,...) `@see` package.Class`#`constructor(Type, Type,...) `@see` package.Class`#`constructor(Type argname, Type argname,...) `@see` package.Class.NestedClass `@see` package.Class `@see` package

上表中的注意事项：
第一种形式（没有类或包）将导致Javadoc工具仅搜索当前类的层次结构。它将找到当前类或接口或者其超类或超接口之一，或其封闭的类或接口之一的一个成员（搜索步骤1-3）。它不会搜索当前包或其他包的其余部分（搜索步骤4-5）。

如果输入没有括号形式的任何方法或构造函数，例如getValue，并且如果没有相同名字的字段，则Javadoc工具将正确创建指向它的链接，不过会打印一条警告消息，提醒您添加括号和参数。如果此方法被重载，Javadoc工具将链接到其搜索遇到的第一个方法，该方法将是不确定的。

不管应用哪种形式，嵌套类必须指定为outer.inner，而不仅仅是inner。
如上所述，散列字符（＃）而不是点（.）将成员与其类分开。这使得Javadoc工具能够解决歧义，因为点还分隔了类，嵌套类，包和子包。但是，Javadoc工具是宽松的，如果你确定不存在歧义，它会正确地解析一个（.），不过它会打印一个警告。

@see的搜索顺序

Javadoc工具将处理出现在源文件（.java），包文件（package.html或package-info.java）或概述文件（overview.html）中的@see标记。在后两个文件中，必须为@see提供完全限定的名字。在源文件中，您可以指定完全限定或部分限定的名字。

当Javadoc工具在.java文件中遇到非完全限定的@see标签时，它会按照与Java编译器相同的搜索顺序搜索指定的名字（不同的是，Javadoc工具不会检测某些命名空间歧义，因为它假设源代码没有这些错误）。Javadoc工具通过所有相关和导入的类和包搜索该名字。它按以下顺序搜索：

当前的类或接口
任何封闭（enclosing）的类和接口，优先搜索最近的
任何超类和超接口，优先搜索最近的
当前包
任何导入的包，类和接口，按import语句的顺序搜索

Javadoc工具继续通过步骤1-3递归搜索它遇到的每个类，直到找到匹配的为止。也就是说，在搜索当前类及其封闭类E之后，它将在搜索E的封闭类之前搜索E的超类。在步骤4和5中，Javadoc工具不会以任何特定的顺序搜索包中的类或接口（该顺序取决于特定的编译器）。在第5步中，Javadoc工具会在java.lang中查找，因为它会被所有程序自动导入。

Javadoc工具不一定在子类中查找，也不会在其他包中查找，即使它们的文档也在同一次运行中生成。例如，如果@see标签位于java.awt.event.KeyEvent类中并引用java.awt包中的名字，则javadoc不会查找该包，除非该类导入了它。

名字如何显示

如果省略label，则将显示package.class.member。通常，它相对于当前的类和包适当地缩短。Javadoc工具只显示必要的最小名字。例如，如果String.toUpperCase()方法包含对同一个类的成员和另一个类的成员的引用，则仅在后一种情况下显示类名，如下表所示。

Use -noqualifier to globally remove the package names.

Type of Reference	Example in `String.toUpperCase()`	Displays As
`@see` tag refers to member of the same class, same package	`@see String#toLowerCase()`	`toLowerCase()` (omits the package and class names)
`@see` tag refers to member of a different class, same package	`@see Character#toLowerCase(char)`	`Character.toLowerCase(char)` (omits the package name, includes the class name)
`@see` tag refers to member of a different class, different package	`@see java.io.File#exists()`	`java.io.File.exists()` (includes the package and class names)

@see的例子
右边的注释显示了如果@see标记位于另一个包中的类（如java.applet.Applet）中，将如何显示该名称。

                                           See also: 
@see java.lang.String                   //  String                           
@see java.lang.String The String class  //  The String class                 
@see String                             //  String                           
@see String#equals(Object)              //  String.equals(Object)            
@see String#equals                      //  String.equals(java.lang.Object)   
@see java.lang.Object#wait(long)        //  java.lang.Object.wait(long)      
@see Character#MAX_RADIX                //  Character.MAX_RADIX              
@see <a href="spec.html">Java Spec</a>  //  Java Spec            
@see "The Java Programming Language"    //  "The Java Programming Language"

可以使用-link选项扩展@see以链接到未被文档记录的类。

@serial 字段描述|include|exclude
用于默认的可序列化字段的文档注释。
可选的字段描述应解释字段的含义并列出可接受的值。字段描述可以跨多行。标准doclet将此信息添加到序列化表单页面。如果可序列化字段在类可序列化之后的某个时间被添加到类中，则应在其主要描述中添加一个语句以标识它的添加版本。include和exclude参数标识是否应在序列化表单页面中包含或排除类或包。他们以如下方式工作：

除非该类（或其包）标记为@serial exclude，否则将包含实现Serializable的公共类或受保护类。
除非该类（或其包）标记为@serial include，否则将排除实现Serializable的私有或包私有类。
例如：javax.swing包标记为@serial exclude（在package.html或package-info.java中）。公共类java.security.BasicPermission标记为@serial exclude。 package-private类java.util.PropertyPermissionCollection标记为@serial include。

类级别的@serial标签会在包级别覆盖@serial。

@serialField 字段名字段类型字段描述
记录可序列化类的serialPersistentFields成员的ObjectStreamField组件。每个ObjectStreamField组件都应使用一个@serialField标签。

@serialData 数据描述
数据描述以序列化形式记录了数据类型和顺序。具体来说，此数据包括writeObject方法写入的可选数据以及Externalizable.writeExternal方法写入的所有数据（包括基本类）。
@serialData标记可以在writeObject，readObject，writeExternal，readExternal，writeReplace和readResolve方法的文档注释中使用。

@since 文本
使用指定的文本向生成的文档添加“Since”标题。该文本没有特殊的内部结构。此标签在任何文档注释中都有效：概述，包，类，接口，构造函数，方法或字段。此标记表示自文本指定的软件版本以来，此更改或功能已存在。例如：
@since 1.5
在Java平台中的源代码里，此标签代表Java平台API规范的版本（不一定在将其添加到参考实现时）。允许使用多个@since标签，类似于多个@author标签。如果prgram元素被多个API使用，你可以使用多个标签。

@throws 类名描述
@throws和@exception标签是同义词。使用类名和描述文本向生成的文档添加“throws”子标题。类名是方法可能抛出的异常的名字。此标签仅在方法或构造函数的文档注释中有效。如果未完全指定此类，则Javadoc工具使用搜索顺序查找此类。对于相同或不同的异常，可以在给定的文档注释中使用多个@throws标签。
为确保记录所有已检查的异常，如果throws子句中的异常不存在@throws标签，则Javadoc工具会自动将该异常添加到HTML输出（没有描述），就像使用@throws标签记录了一样。只有在重写方法中显式声明了异常时，才会将@throws注释从被重写的方法复制到子类。从接口方法复制到实现方法也是如此。您可以使用{@inheritDoc}强制@throws继承文档。

{@value package.class #field}
当在静态字段的doc注释中使用{@value}（没有任何参数）时，它会显示该常量的值：

    /**
     * The value of this constant is {@value}.
     */
    public static final String SCRIPT_START =“<script>”

当与任何文档注释中的参数package.class #field一起使用时，它会显示指定常量的值：

    /**
     * Evaluates the script starting with {@value #SCRIPT_START}.
     */
    public String evalScript(String script) {
    }

参数package.class #field采用与@see的参数相同的形式，但该成员必须是静态字段。这些常量的值也显示在“常量字段值”页面上。

@version 版本文本
使用-version选项时，将指定版本文本的“Version”子标题添加到生成的文档中。此标签用于保存此代码所属软件的当前版本号（与@since相反，后者保存引入此代码的版本号）。 版本文本没有特殊的内部结构。文档注释可能包含多个@version标记。如果有意义，您可以为每个@version标签指定一个版本号，或为每个标签指定多个版本号。在前一种情况下，Javadoc工具在名称之间插入逗号（，）和空格。在后一种情况下，只需将整个文本复制到生成的文档而不进行解析。因此，如果需要使用除逗号之外的其他分隔符，则可以每行使用多个版本号。

标签可以在何处使用

注意：@ see，@ since，@ deprecated，{@ link}，{@ linkplain}和{@docroot}可用于所有文档注释。

概述文档注释标签

注意：{@link}标签在版本1.2中的概述文档中有bug - 文本正确显示但没有链接。 {@docRoot}标签目前不适用于概述文档。

Overview Tags

@see

@since

@author

@version

{@link}

{@linkplain}

{@docRoot}

包文档注释标签

@serial标签只能在此处使用必须include或exclude参数。

Package Tags

@see

@since

@serial

@author

@version

{@link}

{@linkplain}

{@docRoot}

类和接口文档注释标签

@serial标签只能在此处使用必须include或exclude参数。

Class/Interface Tags

@see

@since

@deprecated

@serial

@author

@version

{@link}

{@linkplain}

{@docRoot}

例如：

/**
 * A class representing a window on the screen.
 * For example:
 * <pre>
 *    Window win = new Window(parent);
 *    win.show();
 * </pre>
 *
 * @author  Sami Shaio
 * @version %I%, %G%
 * @see     java.awt.BaseWindow
 * @see     java.awt.Button
 */
class Window extends BaseWindow {
   ...
}

字段文档注释标签

Field Tags

@see

@since

@serial

{@link}

例如：

 /**
  * The X-coordinate of the component.
  *
  * @see #getLocation()
  */
 int x = 1263732;

构造函数和方法文档注释标签

例外：@return不能出现在构造函数中；{@inheritDoc}存在特定的限制（certain restrictions）；@serialData标签只能用于特定的序列化方法上（certain serialization methods）。

Method/Constructor Tags

@see

@since

@deprecated

@param

@return

@throws and @exception

{@link}

例如：

 /**
  * Returns the character at the specified index. An index 
  * ranges from <code>0</code> to <code>length() - 1</code>.
  *
  * @param     index  the index of the desired character.
  * @return    the desired character.
  * @exception StringIndexOutOfRangeException 
  *              if the index is not in the range <code>0</code> 
  *              to <code>length()-1</code>.
  * @see       java.lang.Character#charValue()
  */
 public char charAt(int index) {
    ...
 }

References

1. Javadoc 1.5

2. Javadoc Tool Reference Page (Microsoft Windows)

3. How to Write Doc Comments for Javadoc

4. Cay S. Horstmann,Gary Cornell, Core Java volume I,Ninth Edition

huangsiqian

关注

5
点赞
踩
14

收藏

觉得还不错? 一键收藏
1
评论
复制链接

分享到 QQ

分享到新浪微博

扫一扫

专栏目录

Tag	Introduced in JDK/SDK
`@author`	1.0
`{@code}`	1.5
`{@docRoot}`	1.3
`@deprecated`	1.0
`@exception`	1.0
`{@inheritDoc}`	1.4
`{@link}`	1.2
`{@linkplain}`	1.4
`{@literal}`	1.5
`@param`	1.0
`@return`	1.0
`@see`	1.0
`@serial`	1.2
`@serialData`	1.2
`@serialField`	1.2
`@since`	1.1
`@throws`	1.2
`{@value}`	1.4
`@version`	1.0