@param 用于说明方法参数（含泛型参数），必须紧邻方法声明，参数名须与签名一致；泛型类型变量不可单独用@param，而应在对应实际参数说明中体现其约束和用途。
在 Java 的 Javadoc 中，@param 标签用于描述方法参数，包括泛型参数。关键在于：**泛型类型本身不是参数，参数的声明类型才是文档对象**——所以你要为“带泛型的实际参数”写说明，而不是为类型变量（如 T）单独加 @param。
正确写法：按参数声明的完整类型来标注
如果方法参数是泛型类型（如 List<string></string>、Map<integer user></integer> 或自定义泛型类实例），@param 后直接跟参数名，说明文字中可自然提及泛型含义：
-
✅ 正确示例：
/*** @param users 非空列表，元素为用户对象，顺序表示注册时间先后* @param idToName 映射关系：用户 ID（整数）→ 用户昵称（字符串）*/public void processUsers(List<user> users, Map<integer string> idToName) { ... }</integer></user>
泛型类型变量（如 ）不需要单独 @param
方法签名中的类型形参（如 <t extends comparable>></t>）属于方法的泛型声明，不是运行时传入的参数。Javadoc 规范不要求、也不支持为它写 @param。它的约束和用途应在 @param 对应的具体参数说明中体现，或用 @param + 类型名配合文字解释：
-
✅ 推荐方式：在说明该泛型参数的实际使用参数时，点明其泛型边界意义：
/*** @param <t> （此行不写 @param T！）</t>* @param items 待排序列表，其中元素必须实现 Comparable（即满足 T extends Comparable<t>）</t>*/public <t extends comparable>> void sort(List<t> items) { ... }</t></t>
避免常见错误
-
❌ 错误：给类型变量加 @param
@param T 要排序的元素类型（必须可比较）—— 这不符合 Javadoc 规范，工具（如 javadoc 命令、IDE）会忽略或报 warning。 -
❌ 错误：省略泛型导致语义丢失
写成@param users 用户列表而不提List<user></user>中的User，会让读者无法确认元素类型。 -
❌ 错误：用尖括号包裹参数名
@param <t> items</t>是非法语法，会导致解析失败。
复杂泛型参数的说明技巧
遇到嵌套或通配符泛型（如 Function super Person, ? extends Result>），重点说清「这个参数用来做什么」以及「泛型部分的实际约束」：
- 用自然语言解释通配符意图：
@param mapper 将输入 Person 或其父类实例转换为 Result 或其子类的函数 - 必要时补充典型用法：
// 示例：mapper 可为 p -> new SuccessResult(p.getName())
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
