标签 | 含义 |
---|---|
@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选项。