Java文档注释-JavaDoc标签

标签	含义
@author	指定作者
{@code}	使用代码字体以原样显示信息，不处理HTML样式
@deprecated	指定程序元素已经过时
{@docRoot}	指定当前文档的根目录路径
@exception	标识由方法或构造函数抛出的异常
{@inheritDoc}	从直接超类中继承注释
{@link}	插入指向另外一个主题的内联链接
{@linkplain}	插入指向另外一个主题的内联链接，但是链接以明文显示
{@literal}	以原样显示信息，不处理 HTML 样式
@param	文档化参数
@return	文档化方法的返回值
@see	指定到另一个主题的链接
@serial	文档化默认的可串行化文本域
@serialData	文档化由 writeObject()或writeExternal()方法写入的数据
@serialField	文档化ObjectStreamField组件
@since	当引入特定的变化时，声明发布版本
@throws	与@exception 相同
{@value}	显示常量的值，常量必须是static 类型
@version	指定类的版本

       以@符号开始的标记称为单行标记(也称为块标记)，并且它们必须在自己的行中使用。以花括号开始的标记，例如{@code}，称为内联标记，它们必须在更大的描述中使用。在文档注释中，也可以使用其他标准的 HTML 标记。。但是，有些标记不应当使用，例如标题，因为它们会破坏由javadoc生成的HTML文件的外观。
       因为与文档化源代码有关，所以可以使用文档注释文档化类、接口、域变量、构造函数以及方法。对于所有情况，文档注释必须位于被文档化的条目之前。有些标记，例如@see、@since 以及@deprecated，可以用于文档化所有元素。其他标记只能应用于相关元素。下面分析每个标记。

@author

       @author 标记文档化类或接口的作者，语法如下所示:

@author description

       其中，description通常是作者的姓名。为了将@author 城变量包含到HTML文档中，在执行javadoc时需要指定-author选项。

{@code}

       通过{@code}标记可以将文本(例如代码片段)入到注释中。然后使用代码字体显示文本，而不进行任何进一步的处理，例如使用HTML渲染。语法如下所示:

{@code code-snippet}

@deprecated

       @deprecated标记指示程序元素已经过时。推荐包含@see 或{@link)标记，以告诉程序员有关替代方式的信息。语法如下所示:

@deprecated description

       其中，description是描述过时元素的消息。可以使用@deprecated 标记文档化域变量、方法、构造函数、类以及接口。

{@docRoot}

       {@docRoot}指定了指向当前文档根目录的路径

@exception

       @exception标记描述方法的异常，语法如下所示:

@exception exception-name explanation

       其中，exception-name指定异常的完整限定名，explanation是描述异常发生方式的字符串。@exception标记只能用于文档化方法或构造函数。

{@inheritDoc}

       这个标记用于从直接超类继承注释。

{@link}

       {@link}标记提供指向附加信息的内联链接，语法如下所示:

{@link pkg.class#member text)

       其中，pkg.class#member 指定为其添加链接的类或方法的名称，text是链接显示的字符串。

{@linkplain}

       使用{@linkplain}标记可以插入指向另一个主题的内联链接，链接使用明文显示。除此之外，这个标记与{@link}类似。

{@literal}

       使用{@literal}标记可以将文本嵌入到注释中。文本以原样显示，不进行进一步的处理例如使用HTML渲染。语法如下所示:

{@literal description}

       其中，description 是嵌入的文本。

@param

       @param标记用于文档化参数，语法如下所示:

@param parameter-name explanation

       其中，parameter-name 指定参数的名称。参数的含义是由 explanation 描述的。@param标记只能用于文档化方法或构造函数，抑或泛型类或接口。

@return

       @return标记描述方法的返回值，语法如下所示:

@return explanation

       其中，explanation描述方法返回值的类型和含义。@return 标记只能用于文档化方法

@see

       @see标记提供指向附加信息的引用，最常用的形式如下所示:

@see anchor
@see pkg.class#member text

       在第1种形式中anchor是指向绝对或相对URL的链接。在第2种形式中pkgclass#member指定条目的名称，text 是显示条目的文本。text 参数是可选的，如果没有使用 text 参数，将显示 pkgclass#member 指定的条目。成员名称也是可选的。因此，除了指向特定方法或域变量的引用之外，也可以指定指向包、类或接口的引用。名称可以是完全限定的，也可以部分限定的。但是，成员名称前面的点(如果存在的话)必须替换成散列字符。

@serial

       @serial标记为默认的可串行化域变量定义注释，语法如下所示:

       

@serial description

       其中，description 是关于域变量的注释。

@serialData

       @serialData()标记文档化由writeObject()和writeExternal()方法写入的数据语法如下所示:

@serialData description

       其中，description是数据的注释。

@serialField

       对于实现了 Serializable 接口的类来说，@serialField 标记为 ObjectStreamField 组件提供注释。语法如下所示:

@serialField name type description

       其中，name是域变量的名称，type 是类型，description 是关于域变量的注释。

@since

       @since标记指明元素是在哪个特定的发布版本中引入的，语法如下所示:

 @since release

       其中，release是指定从哪个发布版本开始可以使用这个特性的字符串。

@throws

       @throws标记与@exception 标记具有相同的含义。

{@value}

       {@value}标记具有两种形式。第1种形式显示@value1标记后面的常量的值，常量必须是static类型。这种形式如下所示:

{@value}

       第2种形式显示指定的static 域变量的值。这种形式如下所示:

{@value pkg.cass#field}

       其中，pkg.class#field 指定static 域变量的名称。

@version

       @version标记指定类或接口的版本，语法如下所示:

@version inof

       其中，info 是包含版本信息的字符串，通常是版本号。为了将@version 域变量包含到HTML文档中，在执行iavadoc时需要指定-version选项。