javadoc中文档注释标记的使用

时间:2023-02-24 12:24:33




 

@author

标记@author指定一个类的作者,它的语法如下:

@author description

其中,description通常是编写这个类的作者名字。标记@author只能用在类的文档中。在执行javadoc时,需要指定-author选项,才可以降@author域包括在HTML文档中。

 

@deprecated

@deprecated标记指示不赞成使用一个类或是一个成员。建议使用@see标记指示程序员其他可用的选择。其语法如下:

@deprecated description

其中,description是描述反对的信息。由@deprecated标记指定的信息由编译器识别,包括在生成的.class文件中,因此在编译Java源文件时,程序员可以得到这个信息。@deprecated标记可以用于变量、方法或类的文档中。

 

{@docRoot}

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

 

@exception

@exception标记描述一个方法的异常,其语法如下:

@exception exception-name explanation

其中,异常的完整名称由exception-name指定,explanation是描述异常如何产生的字符串。@exception只用于方法的文档。

 

{@link}

{@link}标记提供一个附加信息的联机超链接。其语法如下:

{@link name text}

其中,name是加入超链接的类或方法的名字,text是显示的字符串。

 

@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

在第一种格式中,anchor是一个指向绝对或相对URL的超链接;对于第二种格式,pkg.class#member指示项目的名字,text是项目的文本显示。文本参数是可选的,如果不使用的话,显示由pkg.class#member指定的项目;成员名也是可选的。因此,除了指向特定方法或者字段的引用之外,你还可以指定一个引用指向一个包、一个类或是一个接口。名字可以使完全限定的,也可以使部分限定的。但是,成员名(若存在的话)之前的点必须被替换成一个散列字符。

 

@serial

@serial标记为默认的可序列化字段定义注释文档。其语法如下:

@serial description

其中,description是字段的注释。

 

@serialData

@serialData标记为writeObject()或者writeExternal()方法编写的数据提供文档。其语法如下:

@serialData description

其中,description是数据的注释。

 

@serialField

@serialField标记为ObjectStreamField组件提供注释,其语法如下:

@serialField name type description

其中,name是域名,type是域的类型,description是域的注释。

 

@since

@since标记声明由一个特定发布版本引入的类或成员,其语法如下:

@since release

其中,release是指示这个特性可用的版本或发布的字符串。@since标记可用在变量、方法和类的文档中。

 

@throws

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

 

@version

@version标记指示类的版本。其语法如下:

@version info

其中,info是包含版本信息的字符串,典型情况下是像1.4这样的版本号。@version标记只用在类的文档中。在执行javadoc时,指定-version选项,可将@version域包含在HTML文档中。