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 hrefhttp://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 首先写入nameString然后写入ageint */ 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 { /** * 用户登录验证 * * pb注意/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