Java / Kotlin：生成方法的规范化

对 新生成或改写 的方法按下列规则整理；仅改与规范化相关的部分，不扩大重构范围。

0. 文档风格：JavaDoc vs KDoc（必须分语言）

同一文件内若同时存在 Java 与 Kotlin，各自文件内严格对应上表，不把 JavaDoc 标签抄进 KDoc。

1. 语言差异：入参 final（仅 Java）

• Java：普通（非下列例外）方法形参必须加 final。
• 例外（一律不加 final）：
  • abstract 抽象方法（含抽象类或接口中 无方法体 的抽象声明）的形参；
  • interface 中的默认方法（default）的形参；
  • 标注 @Override 的实现方法（覆盖父类 / 实现接口）的形参。
• Kotlin：暂不要求为参数加等价约束（按语言惯例即可）。

2. @param / @return（JavaDoc 与 KDoc 均适用块标签）

• 当方法 既有非 void / 非 Unit 的返回类型，又 至少有一个入参 时，必须写 @param（每个入参一条）与 @return。
• void / Unit：若无返回语义，见下文第 6 节；若保留且无返回值可描述，可不写 @return（以项目既有风格为准时跟随项目）。

2.1 @param / @return 行里的类型标注（按语言）

• Java（JavaDoc）：@param intent {@link Intent}、@return {@link Intent} 等，用 {@link 完全限定或简单名}（与项目导入/可读性一致即可）。
• Kotlin（KDoc）：
  • @param：不要在参数名后再写 [类型]；形参类型已在方法签名中，重复标注冗余且易与「正文里对类型的语义说明」混淆。直接写参数语义说明即可。
    • 错误：@param timestamp [Long] 触发用时间戳，大于 0 时执行一次
    • 正确：@param timestamp 触发用时间戳，大于 0 时执行一次
  • @return（以及 <pre> 等允许符号链接处）：仍可用 [类型或符号名] 指向返回类型或相关 API，不用 {@link …}。

3. 返回类型为 Boolean / boolean 时的 @return

两种语言都要求 一句话里写清 true / false 各自含义（可对举），但 字面量标记方式不同：

3.1 Java（JavaDoc）

@return {@code true} XXXX, {@code false} XXX

• 默认：XXXX、XXX 为简短中文说明，与业务语义一致。
• 不必强制改成中文：若已符合上述形式，且两侧说明即可读、能区分语义（例如 @return {@code true} success, {@code false} fail、@return {@code true} yes, {@code false} no 等常见英文对举），保留即可。

3.2 Kotlin（KDoc）

@return `true` XXXX, `false` XXX

• 使用 Markdown 行内代码（反引号）包裹 true / false 字面量，不使用 {@code true}。
• 中英文对举规则与 Java 一节相同：新写默认中文；已对举且表意充分时可保留英文。

4. 类与符号引用（补充说明、正文叙述）

注意：首段摘要中仍遵守第 5 节「禁止直接引用」；{@link …} / `[Type]` / `code` 等应放在 <pre> 块 或 @return 行（Kotlin 的 @param 行不写 [类型]，见第 2.1 节）等允许引用的位置，见下。

5. 方法注释 vs 方法备注（Java / Kotlin 同一套结构）

方法注释（KDoc/JavaDoc 的 首段摘要，通常首行）与 方法备注（其后的补充说明）共用下列规则：

5.1 首段 / 首行：方法注释（摘要）

• 只写方法功能用途：一句话、尽可能简短；可写版本/前提（如「Android 16+：……」）。
• 禁止在首段直接写「代码形态」的引用，包括但不限于：
  • Java：首段内不出现 {@…}（含 {@code …}、{@link …} 等）。
  • Kotlin：首段内不出现 反引号代码 `…`，也不出现 方括号符号链接 […]（避免首行变成「标识符列表」而非摘要）。
• 首段为 纯叙述：说明「是什么 / 干什么」，不夹带可点击或可拷贝的 API 片段。

5.2 方法备注（首段之后的说明块）

• 需要补充的场景、风险、滥用说明、API 名、类/方法引用、文档链接提示等，全部放在首段之后。
• Java 与 Kotlin 均使用 <pre> … </pre> 包裹整块备注。
• <pre> 内允许：
  • Java：{@code startActivity}、{@link Intent} 等；
  • Kotlin：`startActivity`、[Intent]、[IntentFilter] 等 KDoc 写法。
• 与首段分工：首段 = 是什么/干什么；<pre> = 细节、约束、引用、注意事项。

5.3 参考结构

Java：

/**
 * Android 16+：关闭系统对 Intent 重定向的启动侧加固
 * <pre>
 *     极少数合法嵌套 {@code startActivity} 场景
 *     滥用会增大安全风险，仅当确有需要且已评估后再调用；详见官方「Intent 重定向」说明。
 * </pre>
 * @param intent {@link Intent}
 * @return {@link Intent}
 */
@RequiresApi(Build.VERSION_CODES.BAKLAVA)
public static Intent removeLaunchSecurityProtection(final Intent intent) {
    if (intent != null) {
        intent.removeLaunchSecurityProtection();
    }
    return intent;
}

Kotlin（对照 KDoc 写法）：

/**
 * Android 16+：关闭系统对 Intent 重定向的启动侧加固
 * <pre>
 *     极少数合法嵌套 `startActivity` 场景
 *     滥用会增大安全风险，仅当确有需要且已评估后再调用；详见官方「Intent 重定向」说明。
 * </pre>
 * @param intent 待处理的 Intent
 * @return [Intent]
 */
@RequiresApi(Build.VERSION_CODES.BAKLAVA)
fun removeLaunchSecurityProtection(intent: Intent?): Intent? {
    intent?.removeLaunchSecurityProtection()
    return intent
}

要点：首行无 {@}（Java）或无 `…` / […]（Kotlin）；<pre> 内 再放具体 API/类型引用；@param / @return 行按第 2、3 节区分 JavaDoc / KDoc（Kotlin 的 @param 不写 [类型]）。

6. 返回值与 void / Unit

• 非必要不写 void / Unit：若方法本质是「处理入参并供链式/复用」，优先 返回有意义的值；即使「没有额外返回语义」，也可 返回入参对象（如上的 return intent）或项目约定的空值（如 null），便于调用方连续书写。
• 仅在确实无返回值且不宜伪造返回语义时，再使用 void / Unit。

7. 异常与崩溃

• 不得因工具方法未捕获异常而导致主进程 未处理崩溃。
• 可能抛出受检/运行时的逻辑：在方法内 try/catch，记录日志（若项目已有工具类则沿用），返回安全默认值（如 null、false、原入参、空集合等，与语义一致即可）。
• 避免将「易在调用方忘记处理」的异常通过 throws 层层上抛至未捕获崩溃；宁可 在方法边界消化并返回异常语义下的安全值。

8. 执行清单（改写方法时自测）

• Java → JavaDoc、Kotlin → KDoc，未混用 {@link} / `code` 规则。
• Java 形参均已 final（抽象方法、interface default、@Override 方法除外不加）。
• 有非 void / 非 Unit 返回值且有参：@param / @return 齐全。
• boolean / Boolean：@return 分支说明齐全——Java {@code true} / {@code false}；Kotlin `true` / `false`。
• 首段无禁止引用（Java 无 {@}；Kotlin 无首段 `…` / […]）；补充说明在 <pre> 内。
• 类型引用：Java 用 {@link …}；Kotlin 在 @return 行与 <pre> 内 等可用 […]；@param 行不写 [类型]（见第 2.1 节）。
• 能用返回入参/有意义值替代的，避免无意义 void / 无返回语义的 Unit。
• 危险调用已 try/catch，不依赖未捕获异常传播。