什么是Java的javadoc注释_文档注释标签与API网页生成-java教程-PHP中文网

有效的@param必须紧跟方法签名中完全一致的参数名（大小写敏感），@return仅用于有返回值的方法且需与实际类型一致；类说明需用/* /文档注释紧贴声明上方，否则javadoc工具不识别。

什么是java的javadoc注释_文档注释标签与api网页生成

Java 的 javadoc 注释不是写给人看的“备注”，而是给工具生成 API 文档用的结构化元数据。如果 @param 没写对参数名，或 @return 跟方法实际返回类型不一致，javadoc 工具会静默忽略该标签，最终网页里就空着——你检查 HTML 源码都找不到那行字。

实操建议：

@param 后面必须紧跟方法签名中**完全一致的参数名**（大小写敏感），比如方法是 void setAge(int age)，就得写 @param age 年龄，单位为岁，写成 @param Age 或 @param a 都无效
@return 只能用在有明确返回值的方法上；void 方法加 @return 不报错但会被丢弃
多行描述可以换行写，但所有标签（@param、@return、@throws）必须各自独占一行，且不能缩进

示例：

/**  
 * 计算两个整数的和  
 * @param a 第一个加数  
 * @param b 第二个加数  
 * @return 两数之和，不会为 null  
 */  
public int add(int a, int b) { ... }

常见错误是只在类声明前写了普通注释 // 或 /* */，而没用 /** */ 开头的文档注释。只有以 /** 开始、以 */ 结束的块注释，才会被 javadoc 工具识别为文档源。

实操建议：

类、接口、枚举、public 字段、public 方法——只要想出现在最终 API 页面里，就必须用 /** */ 包裹，且紧贴元素上方（中间不能插空行）
默认只处理 public 和 protected 成员；如果要包含包级私有类，得加 -package 参数
路径问题：确保执行 javadoc 时当前目录能正确解析包路径，否则会提示 error: package xxx does not exist，此时要配合 -sourcepath 指定源码根目录
别漏掉 -encoding UTF-8，否则中文注释在 HTML 里变成乱码

@see 是“另请参阅”章节的静态文本入口，生成 HTML 后是普通超链接；{@link} 是内联插入，能直接嵌在句子中，还能自动解析目标是否存在。

在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。

下载

实操建议：

@see 适合列参考项，例如：@see java.util.Collections#sort(List)，它会在页面底部统一归到 “See Also” 栏
{@link} 更灵活，比如：请参考 {@link #getName()} 方法获取名称，渲染后就是带链接的“getName()”字样
两者都支持 #methodName（同类型内）、ClassName#methodName（跨类）、java.util.List#add(E)（跨包带泛型），但注意括号里类型名要跟源码一致，E 不能写成 String
如果目标方法不存在或拼写错误，{@link} 会输出原始字符串（如 {@link #getNmae()} 就真显示成那样），而 @see 不会报错也不提示

这不是注释写错了，而是 javadoc 默认生成的是依赖 stylesheet.css 和 script.js 的静态站点。如果直接双击 index.html 打开（用 file:// 协议），现代浏览器会因安全策略禁止加载本地 CSS/JS，导致白屏或排版崩坏。

实操建议：

必须通过 HTTP 服务访问：用 python3 -m http.server 8000 启动本地服务器，然后浏览器打开 http://localhost:8000
不要手动移动生成的文件夹里的任意文件（尤其是 stylesheet.css），javadoc 生成的路径是硬编码的
如果用了自定义模板（-doclet），确认对应 jar 在 classpath 中，否则会报 error: doclet class xxx not found
JDK 17+ 默认禁用某些反射 API，若用老版本 doclet 报 IllegalAccessException，需加 --add-opens 参数