使用TSLint为TypeScript接口属性加@property注释报错且禁用无效

为什么会触发@property冗余错误？ #

TypeScript本身是强类型语言，接口的属性已经通过类型定义明确了身份和类型信息。TSLint的no-redundant-jsdoc规则会判定JSDoc里的@property标签完全多余——因为TS编译器能直接从接口结构中解析出属性的存在，不需要额外用JSDoc标签重复声明。

比如你原本的写法：

interface UnitValue {
  /**
   * @property value - number with a unit as string
   */
  value: string;
}

这种写法就会触发报错，@property属于画蛇添足的标签。

正确的接口属性注释方式 #

直接去掉@property标签，只保留描述文本即可，TS和TSLint都会认可这种简洁的注释：

interface UnitValue {
  /**
   * number with a unit as string (e.g. "10px", "5rem")
   */
  value: string;
}

如果需要更丰富的说明，可以用@remarks标签或者直接用自然语言描述，比如：

interface UnitValue {
  /**
   * 带单位的数值字符串
   * @remarks 支持CSS长度单位（px/em/rem等），格式为"数字+单位"
   */
  value: string;
}

为什么禁用规则无效？正确的禁用姿势 #

如果你确实有特殊需求要保留@property标签，大概率是你的禁用注释格式不对。TSLint的禁用语法需要精准指定规则名，且位置要正确：

针对单个属性禁用（下一行生效） #

在属性定义的上一行添加精准的禁用注释：

interface UnitValue {
  /* tslint:disable-next-line:no-redundant-jsdoc */
  /**
   * @property value - number with a unit as string
   */
  value: string;
}

或者用单行注释写法：

interface UnitValue {
  // tslint:disable-next-line:no-redundant-jsdoc
  /**
   * @property value - number with a unit as string
   */
  value: string;
}

检查规则名是否正确 #

确保你禁用的规则名是no-redundant-jsdoc——TSLint规则名全小写、用连字符分隔，别写错拼写或大小写。

全局/局部配置禁用 #

如果想在整个文件或项目中禁用该规则，可以修改tslint.json配置：

{
  "rules": {
    "no-redundant-jsdoc": false
  }
}

或者在单个文件顶部添加全局禁用：

/* tslint:disable:no-redundant-jsdoc */

interface UnitValue {
  /**
   * @property value - number with a unit as string
   */
  value: string;
}

额外建议 #

TSLint已经逐渐被ESLint + @typescript-eslint生态取代，如果你还在维护旧的TSLint项目，建议考虑迁移到ESLint——它对TypeScript的支持更完善，社区活跃度也更高。

内容的提问来源于stack exchange，提问作者Kumar Sidharth