JavaDoc注释详解

JavaDoc是Java语言中的一种标准注释格式，用于生成API文档。它使用特殊的注释标记（以/** ... */包围）来描述类、方法、字段等代码元素的功能和参数信息。

以下是一个简单的JavaDoc注释示例：

/**
* 这是一个计算器类，用于执行基本算术运算。
* @author 开发者姓名
* @version 1.0
*/
public class Calculator {
/** * 计算两个整数的和。
 * @param a 第一个加数
* @param b 第二个加数
* @return 两个加数的和
*/
public int add(int a, int b) {
return a + b;
}
}

JavaDoc注释通常包含以下元素：

1. 简要描述（首行）
2. 详细描述（后续行）
3. 标记（@开头）如@param、@return、@throws等

使用javadoc工具可以基于这些注释生成HTML格式的API文档。

以下是除常见标记外的其他有用标记：

1. 类/接口相关标记

• @since - 指定类/方法被引入的版本号‌
• @deprecated - 标记过时的API（需配合@see或{@link}说明替代方案）‌
• @serial - 描述序列化字段‌
• @serialField - 说明ObjectStreamField组件‌

2. 方法相关标记

• @exception - 同@throws的别名‌
• @serialData - 描述writeObject()写入的数据‌
• @hidden - 隐藏特定元素（Java 9+）‌

3. 文档增强标记

• {@code} - 以代码字体显示文本（不解析HTML）‌
  示例：{@code List<String>} → 显示为List<String>
• {@literal} - 原样显示特殊字符（如<,>) ‌
• {@docRoot} - 指向文档根目录的相对路径‌
• {@inheritDoc} - 继承父类注释‌
• {@index} - 创建搜索关键字（Java 9+）‌

4. 交叉引用标记

• @see - 创建超链接到其他类/方法‌
  格式：@see 类名#方法名(参数类型)
• {@link} - 行内链接（类似@see但更灵活）‌
  示例：参见{@link java.util.ArrayList}

5. 特殊内容标记

• {@value} - 显示常量值‌
  示例：{@value java.awt.Color#RED}
• {@systemProperty} - 标记系统属性（Java 12+）‌
• {@summary} - 提供简洁摘要（Java 12+）‌

使用建议：

1. 复杂注释可嵌入HTML标签如<p>,<ul>等实现段落和列表‌
2. 通过javadoc -d命令指定输出目录，配合-author/-version选项控制显示‌
3. 在IDEA等IDE中可配置Live Templates自动生成文档注释模板