Java 文档注释
javadoc 标签、文档注释写法与生成 HTML 文档。
javadoc 标签
Common tags: @param for parameters, @return for the result, @throws for exceptions, @author, @since, @see for related links and @deprecated for retired APIs.
| Tag | Used on | Meaning |
|---|---|---|
| @param name desc | method / constructor | Describe a parameter |
| @return desc | method | Describe the return value |
| @throws Type why | method | Describe a thrown exception |
| @author name | class / interface | Author |
| @since version | any | Since which version |
| @deprecated | any | Mark as obsolete |
文档注释的写法
The first sentence is the summary shown in method lists, so state what it does in one line. A blank line separates details. HTML tags like <p> and <code> are allowed.
/**
* 数值计算工具。
*
* <p>所有方法都是无状态的静态方法，可安全并发调用。
*
* @author BackendWiki
* @since 1.0
*/
public class SquareNum {
/**
* 返回参数的平方。
*
* @param num 待计算的整数
* @return {@code num * num}
*/
public static int square(int num) {
return num * num;
}
/**
* 整数除法。
*
* @param a 被除数
* @param b 除数，不能为 0
* @return 商
* @throws ArithmeticException 当 {@code b == 0}
*/
public static int div(int a, int b) {
return a / b;
}
public static void main(String[] args) {
System.out.println(square(4));
System.out.println(div(6, 3));
}
}16
2javadoc 输出什么
javadoc -d doc src/*.java writes a full HTML site under doc/: class index, method summary and per-method detail. That is exactly what Ctrl+Q shows in the IDE.
$ javadoc -d doc -encoding UTF-8 -charset UTF-8 SquareNum.java
正在生成 doc/SquareNum.html ...
正在构建所有类和包的所有方法索引 ...@param or @return only warns; the build continues. Add -Xwerror in CI to fail instead, keeping docs in sync with code.javadoc 标签
常用标签：@param 描述参数、@return 描述返回值、@throws 描述可能抛出的异常、@author 作者、@since 起始版本、@see 相关链接、@deprecated 已废弃。
| 标签 | 用于 | 含义 |
|---|---|---|
| @param 名 描述 | 方法 / 构造方法 | 说明参数 |
| @return 描述 | 方法 | 说明返回值 |
| @throws 类型 原因 | 方法 | 说明抛出的异常 |
| @author 名字 | 类 / 接口 | 作者 |
| @since 版本 | 任意 | 从哪个版本开始 |
| @deprecated | 任意 | 标记为废弃 |
文档注释的写法
第一句是摘要，会被抽到方法列表里，所以要用一句话说清「做什么」。空一行后写细节。HTML 标签（<p>、<code>）可以直接用。
/**
* 数值计算工具。
*
* <p>所有方法都是无状态的静态方法，可安全并发调用。
*
* @author BackendWiki
* @since 1.0
*/
public class SquareNum {
/**
* 返回参数的平方。
*
* @param num 待计算的整数
* @return {@code num * num}
*/
public static int square(int num) {
return num * num;
}
/**
* 整数除法。
*
* @param a 被除数
* @param b 除数，不能为 0
* @return 商
* @throws ArithmeticException 当 {@code b == 0}
*/
public static int div(int a, int b) {
return a / b;
}
public static void main(String[] args) {
System.out.println(square(4));
System.out.println(div(6, 3));
}
}16
2javadoc 输出什么
javadoc -d doc src/*.java 在 doc/ 下生成一整套 HTML：类列表、方法摘要、每个方法的详细说明。IDE 里按 Ctrl+Q 看到的就是这些内容。
$ javadoc -d doc -encoding UTF-8 -charset UTF-8 SquareNum.java
正在生成 doc/SquareNum.html ...
正在构建所有类和包的所有方法索引 ...@param / @return 写错名字时 javadoc 会报警告但不中断构建。CI 里可以加 -Xwerror 把它变成失败，避免文档和代码脱节。