类型守卫函数是否有@returns之外更合适的TSDoc标签？

架构老林

2026-8-19

类型守卫函数的TSDoc注释优化方案

TSDoc标准里并没有@casts这类官方标签，但我们可以用更贴合类型守卫特性的方式来写注释，比单纯描述布尔返回值要清晰得多。

原`@returns`注释的问题

你之前写的@returns只说明了返回true/false的业务含义，但类型守卫的核心价值是告诉TypeScript：当返回true时，参数的类型会被收窄为特定类型——这层关键信息在原注释里没体现出来，对依赖类型提示的开发者来说不够直观。

推荐的注释写法

1. 强化`@returns`，明确类型收窄逻辑

直接在@returns里把返回值和类型断言的结果绑定起来，TypeScript工具链（比如VS Code）能直接识别这层信息：

/**
 * 判断宠物是鱼还是鸟的类型守卫
 * 
 * @param pet - 类型为鱼或鸟的宠物实例
 * @returns 返回`true`时，`pet`会被TypeScript自动收窄为`Fish`类型；返回`false`时则为`Bird`类型
 */
function isFish(pet: Fish | Bird): pet is Fish {
  return (pet as Fish).swim !== undefined;
}

2. 用`@remarks`补充判断细节

如果需要说明具体的判断逻辑，可以搭配@remarks标签：

/**
 * 判断宠物是鱼还是鸟的类型守卫
 * 
 * @param pet - 类型为鱼或鸟的宠物实例
 * @returns 返回`true`时，`pet`会被TypeScript自动收窄为`Fish`类型；返回`false`时则为`Bird`类型
 * @remarks 通过检查宠物是否存在`swim`方法来区分类型：有该方法则为鱼，否则为鸟
 */
function isFish(pet: Fish | Bird): pet is Fish {
  return (pet as Fish).swim !== undefined;
}