@longzai-intelligence-eslint/eslint-plugin-tsdoc

TSDoc ESLint 插件，提供 TSDoc 注释规范检查规则，用于强制执行统一的 TSDoc 注释风格，提高代码文档的完整性和一致性。

安装

bun add --dev @longzai-intelligence-eslint/eslint-plugin-tsdoc

使用

使用推荐配置

// eslint.config.ts
import tsdocPlugin from '@longzai-intelligence-eslint/eslint-plugin-tsdoc';

export default [tsdocPlugin.configs.recommended];

自定义配置

// eslint.config.ts
import tsdocPlugin, { PLUGIN_NAME } from '@longzai-intelligence-eslint/eslint-plugin-tsdoc';

export default [
  {
    plugins: {
      [PLUGIN_NAME]: tsdocPlugin,
    },
    rules: {
      [`${PLUGIN_NAME}/require-tsdoc`]: 'error',
      [`${PLUGIN_NAME}/require-param`]: 'error',
      [`${PLUGIN_NAME}/require-returns`]: 'error',
    },
  },
];

规则列表

核心规则

| 规则名称 | 说明 | 推荐级别 | | --------------------------- | --------------------------------------------- | -------- | | require-tsdoc | 要求函数、方法、类、变量、接口等有 TSDoc 注释 | error | | require-param | 要求函数参数有 @param 文档 | error | | require-returns | 要求函数返回值有 @returns 文档 | error | | require-description | 要求 TSDoc 注释包含描述 | error | | require-param-description | 要求 @param 包含描述 | error | | require-returns-description | 要求 @returns 包含描述 | error | | require-type-param | 要求泛型类型参数有 @typeParam 文档 | error |

格式规则

| 规则名称 | 说明 | 推荐级别 | | ------------------------------ | ---------------------------- | -------- | | no-description-tag | 禁止使用 @description 标签 | error | | param-hyphen-format | 要求 @param 使用连字符格式 | error | | require-blank-line-before-tags | 要求标签前有空行 | error | | separator-format | 检查分隔符格式 | - | | todo-format | 检查 TODO 注释格式 | warn |

异常规则

| 规则名称 | 说明 | 推荐级别 | | ------------------- | ----------------------------- | -------- | | require-throws | 要求抛出异常有 @throws 文档 | warn | | require-throws-type | 要求 @throws 包含异常类型 | warn |

废弃规则

| 规则名称 | 说明 | 推荐级别 | | ------------------------------ | ------------------------------- | -------- | | require-deprecated-alternative | 要求 @deprecated 包含替代方案 | warn |

质量规则

| 规则名称 | 说明 | 推荐级别 | | ---------------------------------- | ----------------------- | -------- | | no-legacy-jsdoc-tags | 禁止使用旧版 JSDoc 标签 | error | | no-placeholder-description | 禁止使用占位描述 | error | | no-commented-code | 禁止注释掉的代码 | warn | | require-multiline-property-comment | 要求多行属性注释 | error |

依赖

• eslint >= 9.0.0
• typescript >= 5.0.0
• @longzai-intelligence-eslint/eslint-utils

开发

# 安装依赖
bun install

# 构建
bun run build

# 测试
bun run test

# 类型检查
bun run typecheck

# Lint
bun run lint