Java 知识量:11 - 45 - 220
Java文档注释是用于生成API文档的注释,可以出现在类、接口、方法、构造器和成员字段的前面。文档注释对于代码的自动文档生成工具(如javadoc工具)是非常有用的,它们可以使开发者轻松了解代码的用途、参数、返回值等。
Java文档注释的结构可以分为两个主要部分:描述部分和标记部分。
描述部分:用一段简短的话对这个类或方法等进行描述。
标记部分:这部分包括@param、@return、@see等标记,用于提供关于方法参数、返回值和相关类的更多信息。
以一个类为例,文档注释可能如下:
/** * 这是一个用于表示学生的类 */ public class Student { //... }
在这个例子中,“这是一个用于表示学生的类”就是描述部分。
如果是一个方法,文档注释可能如下:
/** * 这是一个用于获取学生姓名的方法 * @param name 学生的姓名 * @return 返回该学生的姓名 */ public String getName(String name) { //... }
在这个例子中,“这是一个用于获取学生姓名的方法”是描述部分,“@param name 学生的姓名”和“@return 返回该学生的姓名”是标记部分,用于详细说明方法的参数和返回值。
Java文档注释标签是用于在Java代码中提供额外信息的特殊注释。这些标签以"/**"开始,以"*/"结束。以下是常用的一些Java文档注释标签:
@author:用于表示创建编辑这个类或者方法的作者。使用方法:@author Rex,这将在生成的文档中显示作者信息。
@see:用于指向包、类、方法、属性等,可以在注释中实现链接跳转。使用方法:@see package.class#member,如果跳转同一个类中就@see #member即可,同一个包中就@see class#member。
@since:标明一个类、方法或者其他标识符是在哪个特定版本开始添加进来的。使用方法:@since 1.0表明1.0版本添加进来的。
@return:用于描述返回信息,返回的内容,返回的数据形式。使用方法:@return parameterName description表明parameterName参数的类型、信息或者功能。
@throws:用于描述抛出异常的类型、信息、功能。
@version:用于标识注释对象的版本号。
在Java中,行内文档注释标签通常用于在代码中添加简短的说明或链接。以下是常用的一些行内文档注释标签:
@param:用于描述方法参数的名称和类型。
@return:用于描述方法的返回值类型和意义。
@throws:用于说明方法可能抛出的异常类型。
@link:用于在注释中添加链接地址。
这些行内文档注释标签可以帮助开发者更好地理解代码,并在生成文档时自动提取相关信息。例如,使用@param标签可以这样写:@param [paramName] [paramDescription],其中[paramName]是参数名称,[paramDescription]是参数说明。
交叉引用是指引用其他类、方法或字段的文档注释。这可以帮助开发者在文档中更好地了解和组织代码。
要创建交叉引用,请使用以下语法:
[#sectionName|linkText]
其中,sectionName是要引用的部分的名称,linkText是要显示的链接文本。
例如,假设有一个方法doSomething(),并且想在另一个方法的文档注释中引用它。可以使用以下语法:
/** * This method does something. See {@link #doSomething()} for more information. */ public void doSomethingElse() { // ... }
在这个例子中,{@link #doSomething()}是一个交叉引用,它指向doSomething()方法的文档注释。当生成文档时,将生成一个链接到doSomething()方法的链接。
还可以使用{@linkplain #doSomething()}语法来显示链接文本,而不是将文本放在方括号中。例如:
/** * This method does something. See {@linkplain #doSomething()} for more information. */ public void doSomethingElse() { // ... }
这个例子生成一个链接到doSomething()方法的链接。
Copyright © 2017-Now pnotes.cn. All Rights Reserved.
编程学习笔记 保留所有权利
MARK:3.0.0.20240214.P35
From 2017.2.6