javadoc 输出 & 避坑
知道怎么写只是第一步，避开这些坑才能让注释真正发挥作用。
javadoc 输出什么
- 把 Java 程序的源代码作为输入，输出一些包含程序注释的 HTML 文件
- 每一个类的信息将在独立的 HTML 文件里
- 还会输出继承树形结构和索引
- 基本命令：
javadoc SquareNum.java
坑位 1：@return 用在 void 上
- void 返回类型的方法不能用
@return标签 - javadoc 会发出警告：
@return tag cannot be used in method with void return type - ✅ 解决：void 方法删掉 @return 即可
坑位 2：多行注释嵌套
/* 外层 /* 内层 */ 外层 */—— 第一个*/就提前结束注释- 后面的内容会被当成代码 → 编译报错
- ✅ 解决：禁止嵌套，改用
//逐行注释
注释最佳实践
- 注释解释 WHY（为什么这么做），而不是 WHAT（做了什么）——代码本身已经说明了 WHAT
- 改动代码时同步更新注释，过期的注释比没注释更糟糕
- IDE 快捷键 /** + Enter 可自动生成方法文档注释骨架