java单行注释用//，多行用/.../；javadoc需/**开头且紧贴声明；@param参数名须与签名完全一致；生成时需指定-encoding utf-8防乱码。
Java里怎么写单行和多行注释
单行注释用 //，从它开始到行尾都被忽略；多行注释用 /* ... */，能跨行但不能嵌套。别在 /* 里面再写 /*，编译器会报错： unclosed comment。
常见错误是把 // 当成“局部开关”去临时屏蔽代码块——结果漏掉某一行末尾的分号或括号，导致语法错误。更稳妥的做法是用 IDE 的快捷键（比如 Ctrl+/）批量注释，它会自动按行加 //，不破坏结构。
-
//只影响当前行，适合说明某一行逻辑或临时调试 -
/* ... */适合说明一段连续代码的意图，比如算法步骤，但别用来包一大段废弃代码 - 别用
/* ... */包含带//的行，容易误判结束位置
Javadoc注释怎么写才被javadoc命令识别
只有以 /** 开头、*/ 结尾的注释块，并且紧贴在类、方法、字段声明**正上方**时，才会被 javadoc 工具提取。少一个 *（写成 /*）或空了一行，就直接失效。
典型错误是写成这样：
立即学习“Java免费学习笔记（深入）”；
public class Example {
/* 这不是Javadoc */
public void run() { ... }
}或者这样：
public class Example {
<pre class='brush:java;toolbar:false;'>/**
* 这看起来像，但上面空了一行 → 不生效
*/
public void run() { ... }}
- 必须用
/**（两个星号），不是/* - 必须紧邻声明，中间不能有空行
- 常用标签如
@param、@return、@throws要顶格写，冒号后空一格，描述接在后面 - 标签顺序无所谓，但建议按惯例：先
@param，再@return，最后@throws
为什么@param写错类型或参数名会导致生成失败
javadoc 不校验 @param 后面写的类型或名字是否真实存在，但它会检查「是否拼写错了当前方法的参数名」。如果写成 @param userId，而方法签名实际是 void login(String username)，那么生成的 HTML 文档里这个参数项会显示为“unknown parameter”，且 javadoc 命令默认不报错——你得加 -Xdoclint:all 才能在控制台看到警告。
- 参数名必须和方法/构造器签名中**完全一致**（包括大小写）
-
@param后不要写类型，只写参数名，例如@param name，不是@param String name - 没有对应参数却写了
@param，文档里会出现空白条目，容易误导调用方 - 重载方法之间共用同一套 Javadoc 模板时，最容易漏改
@param名称
生成Javadoc时中文乱码和路径空格问题怎么解
Windows 上用 javadoc 默认用系统编码（通常是 GBK），源文件是 UTF-8 就会乱码；另外，如果项目路径含空格（比如 C:\My Project\src），命令行直接执行常会中断，报错类似 error: invalid flag: Project\src。
- 强制指定编码：加
-encoding UTF-8 -charset UTF-8，两个都得写，缺一不可 - 路径含空格时，用双引号包裹整个
-sourcepath或输入路径，例如-sourcepath "C:\My Project\src" - 避免用
file://协议写路径，javadoc 对 URL 格式支持不稳定 - 如果用 Maven，推荐配
maven-javadoc-plugin并设<encoding>UTF-8</encoding>，比手敲命令更稳
真正麻烦的是团队协作时有人用 Mac、有人用 Windows，IDE 自动生成的 Javadoc 模板默认编码不一致，光靠个人设置很难统一。最省事的方式是把 javadoc 命令封装进脚本，固定编码和路径处理逻辑。
