2024-09-07 06:00PM
1.文档注释格式
java文档注释（Javadoc）用于生成API文档，它允许开发者为类、方法和字段等添加说明。
1) 所有的java文档注释都以 /** 开头， */ 结尾，通常放在类或方法的声明之前
2) 文档注释覆盖范围包括：类、接口、方法、构造器、成员字段，如果写在其他位置，比如函数内容部，则被视为无效文档注释
3) 每个java文档注释都要和其后对应的类/方法/字段保持同样的缩进
4) java文档注释的内容，支持采用HTML语法规则书写，同时也支持一些额外的辅助标签
在类/方法上的文档标注一般分为三段，顺序如下：
第一段：概要描述，通常用一句话或者一段话简要描述该类的作用，以英文句号结束，这句话会被提取并放到索引目录中。
第二段：详细描述，通常用一段话或者多段话详细描述该类的作用，每段话都以英文句号结束，详细描述中可以使用HTMl标签，如<p>,<pre>,<a>,<li>等标签。
第三段：文档标记，通常用于标注作者，创作时间、参阅类等信息，描述部分和文档标记之间必须空一行。
eg：
/**
* 这是一个示例类，演示如何使用 Javadoc 注释。
*/
public class Example {
/**
* 计算两个整数的和。
*
* @param a 第一个整数
* @param b 第二个整数
* @return 两个整数的和
* @throws IllegalArgumentException 如果任一参数为负
*/
public int add(int a, int b) {
if (a < 0 || b < 0) {
throw new IllegalArgumentException("参数不能为负数");
}
return a + b;
}
}
2.文档标签
javadoc工具可以识别文档注释中的一些特殊标签，这些标签一般以@开头，后跟一个指定的名字，有的也以{@开头，以}结束，javadoc可以识别的标签如下：
@author
说明：用于指明作者或者组织，可以附加邮箱或者超链接，如果有多个作者就用多个标签，适用范围：包、类、接口。
eg：
/**
* @author xxxx
* @author xxx@123.com
* @author <a href="mailto:xxx@123.com">xxxxx</a>
*/
@since
说明：用于指明最早出现在哪个版本，可填版本号或日期，有时也可以表名运行的JDK版本，适用范围：包、类、接口、方法、成员属性、构造器(类似于go语言的struct)
eg：
/**
* @since 1.4
* @since 15 April 2001
* @since JDK1.5
*/
@version
说明：用于指明当前版本号。适用范围：包、类、接口
eg：
/**
* @version 1.8.3.4
*/
@code
用于将一些关键字或代码片段格式化为代码样式，以便在生成的文档中清晰可读。它通常用于描述某个方法或类时引用代码示例。
eg：
public class Example {
/**
* 计算两个整数的和。
*
* @param a 第一个整数
* @param b 第二个整数
* @return 两个整数的和
* @code
* // 示例用法
* Example example = new Example();
* int result = example.add(5, 10);
* System.out.println(result); // 输出 15
* @endcode
*/
public int add(int a, int b) {
return a + b;
}
}
@code 后面可以跟随代码片段，生成的文档会将其格式化为代码样式。
@endcode 用于表示代码片段的结束，尽管在大多数情况下，可以省略这一行，具体取决于文档生成工具的实现。
@return
说明：对函数返回值的注释。适用范围：方法
/**
* @return <code>true</code> 执行成功;<code>false</code> 执行失败.
*/
@value
说明：只能用于对常量进行注释，该标签常用于写在字段上的javadoc注释。适用范围：方法、成员属性
eg：
/**
* Default start value. {@value #START_VALUE}
*/
@throws 和 @exception
说明：用户描述构造函数或方法所会抛出的异常。适用范围：方法、构造器
/**
* @throws IllegalArgumentException
* if {@code fromIndex > toIndex}
*/
@link 、@linkplain 和 @see
说明：用于创建一个超链接到相关代码。
适用范围：包、类、接口、方法、成员属性、构造器
注意事项：
1) @link 和 @linkplain的区别在于：@link直接将将超链接中的地址当作显示的文本，其格式为 {@link 地址}；而 @linkplain可以自行设定显示的文本，其格式为{@link 地址 显示文本}，三个字段用空格隔开。
2) @link 和 @see的区别在于：@link可以放在某一行中的任意位置；而 @see必须放在某一行中的最开始。
/**
* xxx {@link java.lang.String#charAt(int)}
* xxx {@link #sort(Object[])}
* xxx {@linkplain Comparable natural ordering}
* @see #deepHashCode(Object[])
*/
@inheritDoc
说明：用于继承父类的 javadoc 注释，父类的文档注释会被拷贝到子类。适用范围：方法
eg：
/**
* {@inheritDoc}
* <p>
* The speed of tiger will be returned.
*
* @return the speed of tiger
*/
@deprecated
说明：告诉用户该 API 已过时，并且已被哪些新的 API 取代了。用@see或 @link指向新的API。该旧的 API 之所以不删掉，通常是为了兼容性考虑。。适用范围：包、类、接口、方法、成员属性、构造器
eg：
/**
* @deprecated As of JDK 1.1, replaced by
* {@link #setBounds(int, int, int, int)}
*/
@serial
说明：说明一个序列化属性。适用范围：方法、成员属性
/**
* @serial description
*/
@serialData
说明：用于说明通过 writeObject() 和 writeExternal() 方法写的数据。。适用范围：方法、成员属性
/**
* @serialData description
*/
@serialField
说明：用于说明一个 ObjectStreamField 组件。适用范围：方法、成员属性
/**
* @serialField name type description
*/
最后，在使用文档注释时，通常会按照如下顺序进行使用。
@author
@version
@param
@return
@exception / @throws
@see
@since
@serial / @serialField / @serialData
@deprecated
3. java api 文档生成方式
使用 Javadoc 工具，可以通过命令行生成 HTML 格式的文档：
javadoc -d doc Example.java
这将创建一个名为 doc 的目录，里面包含生成的 API 文档。
登录
请登录后再发表评论。
评论列表:
目前还没有人发表评论