Javadoc 常用标签及用法
基础标签
1.@param- 参数说明
/** * 计算两个数的和 * @param a 第一个加数 * @param b 第二个加数 */ public int add(int a, int b) { return a + b; }2.@return- 返回值说明
/** * 获取用户姓名 * @return 用户的姓名，如果不存在返回null */ public String getName() { return this.name; }3.@throws/@exception- 异常说明
/** * 加载配置文件 * @throws IOException 当配置文件不存在或无法读取时抛出 * @throws IllegalArgumentException 当配置文件格式错误时抛出 */ public void loadConfig() throws IOException { // 方法实现 }4.@deprecated- 废弃说明
/** * 旧版本的登录方法 * @deprecated 从v2.0开始废弃，请使用 {@link #login(String, String)} 方法 * @see #login(String, String) */ @Deprecated public void oldLogin() { // 旧实现 }5.@see- 相关链接
/** * 用户登录验证 * @see UserManager#authenticate(String, String) * @see <a href="http://example.com/auth">认证文档</a> * @see "Java编程规范" */ public boolean login(String username, String password) { // 方法实现 }6.@since- 版本说明
/** * 新的数据加密方法 * @since 1.5.0 */ public String encryptData(String data) { // 方法实现 }7.@version- 版本号
/** * 数据库连接工具类 * @version 2.1.0 */ public class DBUtil { // 类实现 }8.@author- 作者信息
/** * 字符串工具类 * @author 张三 * @author 李四 */ public class StringUtils { // 类实现 }内联标签（在描述中使用）
9.{@code}- 代码显示
/** * 设置文件路径 * 例如：{@code setPath("/usr/local/bin")} * 注意：路径必须是绝对路径 */ public void setPath(String path) { this.path = path; }10.{@link}/{@linkplain}- 内部链接
/** * 创建用户实例 * 使用示例： * <pre> * User user = new User(); * user.setName("张三"); * user.setAge(25); * </pre> * * 更多信息请参考 {@link UserManager#createUser(User)} * 或查看 {@linkplain http://example.com/docs 用户文档} */ public class User { private String name; private int age; }11.{@value}- 常量值引用
/** * 应用程序常量定义 */ public class AppConstants { /** * 默认超时时间（毫秒） * @see #DEFAULT_RETRY_COUNT */ public static final int DEFAULT_TIMEOUT = 5000; /** * 默认重试次数：{@value #DEFAULT_RETRY_COUNT} */ public static final int DEFAULT_RETRY_COUNT = 3; }12.{@literal}- 原样显示文本
/** * 比较两个对象 * 注意：{@literal x < y} 表示x小于y * 如果不使用{@literal}，<会被解析为HTML标签 */ public boolean compare(int x, int y) { return x < y; }高级标签
13.@serial- 序列化字段说明
/** * 用户序列化类 */ public class User implements Serializable { /** * @serial 用户的唯一标识符 */ private long id; /** * @serialField name String 用户姓名 * @serialField age int 用户年龄 */ private static final ObjectStreamField[] serialPersistentFields = { new ObjectStreamField("name", String.class), new ObjectStreamField("age", int.class) }; }14.@serialData- 序列化数据说明
/** * 自定义序列化 * @serialData 首先写入name（String），然后写入age（int） */ private void writeObject(ObjectOutputStream out) throws IOException { out.defaultWriteObject(); out.writeUTF(name); out.writeInt(age); }15.@hidden- 隐藏文档
/** * 内部使用的方法，不对外公开 * @hidden 此方法仅供框架内部使用 */ void internalMethod() { // 内部实现 }16.{@index}- 创建搜索索引
/** * 处理{@index JSON}格式的数据 * 支持{@index XML}和{@index YAML}格式 */ public class DataProcessor { // 类实现 }完整示例
/** * 用户管理类 * <p>提供用户的增删改查等操作</p> * * @author 张三 * @author 李四 * @version 3.2.1 * @since 1.0.0 */ public class UserManager { /** * 用户登录验证 * * <p><b>注意：</b>此方法会验证用户密码是否过期</p> * * @param username 用户名，不能为空 * @param password 密码，长度必须大于6位 * @return 登录成功返回true，失败返回false * @throws IllegalArgumentException 当用户名或密码格式错误时抛出 * @throws UserNotFoundException 当用户不存在时抛出 * @throws AccountLockedException 当账户被锁定时抛出 * @see User#validate() * @see #logout() * @since 2.0.0 */ public boolean login(String username, String password) throws IllegalArgumentException, UserNotFoundException, AccountLockedException { // 方法实现 return true; } /** * 旧版登录方法 * @deprecated 从3.0.0开始废弃，请使用 {@link #login(String, String)} * @param username 用户名 * @param password 密码 * @return 登录状态 */ @Deprecated(since = "3.0.0") public boolean oldLogin(String username, String password) { // 旧实现 return false; } }使用建议
必选标签：
@param、@return、@throws应尽可能使用版本控制：使用
@since和@deprecated管理API生命周期交叉引用：使用
@see和{@link}建立文档间的关联代码示例：在复杂方法中使用
<pre>{@code ...}</pre>提供示例HTML标签：可以在描述中使用
<p>,<b>,<i>,<ul>,<li>等HTML标签增强可读性
生成文档命令
# 生成标准文档 javadoc -d doc -sourcepath src com.example # 生成带作者和版本信息的文档 javadoc -d doc -sourcepath src -author -version com.example # 生成包含私有成员的文档 javadoc -d doc -sourcepath src -private com.example