ESLint Plugin for TSDoc Syntax Validation

0.5.2 · active · verified Sun Apr 19

eslint-plugin-tsdoc is an ESLint plugin designed to enforce the TSDoc specification for documentation comments within TypeScript projects. It ensures that doc comments adhere to a structured format, improving consistency and machine-readability for tools like API extractors. The plugin's current stable version is 0.5.2 and it is actively maintained by the TSDoc project, indicating ongoing support and alignment with the TSDoc specification. Unlike general JSDoc validators, this plugin is specifically tailored for TypeScript and integrates seamlessly with the `@typescript-eslint` ecosystem, requiring its parser and plugin for correct operation. Its primary differentiation is strict adherence to the TSDoc standard, providing a more formal and type-aware documentation approach compared to looser JSDoc interpretations. Release cadence is typically driven by TSDoc spec updates or bug fixes, rather than a fixed schedule.

Common errors

```
Error: Plugin "tsdoc" was not found. Please check the plugin name, or consider installing it with npm.
```
cause The plugin name in the ESLint configuration `plugins` array is incorrect or missing the `eslint-plugin-` prefix.

fix Change `plugins: ['tsdoc']` to `plugins: ['eslint-plugin-tsdoc']` or ensure the package is correctly installed.
```
Parsing error: 'parserOptions.project' has been set for @typescript-eslint/parser. The file does not exist: /path/to/project/undefined
```
cause `parserOptions.project` or `tsconfigRootDir` is incorrectly configured, leading ESLint to look for a non-existent `tsconfig.json` file.

fix Verify that `parserOptions.project` correctly points to your `tsconfig.json` (e.g., `./tsconfig.json`) and that `tsconfigRootDir` is correctly set to `__dirname` or the absolute root of your project containing `tsconfig.json`.
```
Rule 'tsdoc/syntax' is not found.
```
cause The `tsdoc/syntax` rule is referenced in the `rules` section but the `eslint-plugin-tsdoc` plugin is not correctly loaded, or the rule name is mistyped.

fix Ensure `eslint-plugin-tsdoc` is listed in the `plugins` array in your `.eslintrc.js` and that the rule name `tsdoc/syntax` is spelled correctly, including the `tsdoc/` prefix.

Warnings

breaking Major versions of `@typescript-eslint/parser` or `@typescript-eslint/eslint-plugin` can introduce breaking changes that might affect how `eslint-plugin-tsdoc` interacts with your TypeScript code. Ensure compatibility when upgrading.
Fix: Refer to the release notes for `@typescript-eslint` and `eslint-plugin-tsdoc` when upgrading to identify necessary configuration adjustments or minimum version requirements.
gotcha Incorrect configuration of `parserOptions.project` or `tsconfigRootDir` in your ESLint setup can prevent `@typescript-eslint/parser` (and thus `eslint-plugin-tsdoc`) from correctly resolving type information, leading to parsing errors or rules not firing correctly, especially in monorepos.
Fix: Verify that `parserOptions.project` points to the correct `tsconfig.json` file for the linted project, and `tsconfigRootDir` is set to the absolute path of the directory containing `tsconfig.json` relative to your ESLint config.
gotcha Failing to install or correctly configure `@typescript-eslint/parser` and `@typescript-eslint/eslint-plugin` will cause ESLint to fail to parse TypeScript files or recognize the TSDoc plugin's context.
Fix: Ensure `@typescript-eslint/parser` and `@typescript-eslint/eslint-plugin` are installed as dev dependencies and properly configured in your `.eslintrc.js` file under `parser`, `plugins`, and `extends`.

Install

npm install eslint-plugin-tsdoc npm
yarn add eslint-plugin-tsdoc yarn
pnpm add eslint-plugin-tsdoc pnpm

Imports

eslint-plugin-tsdoc (plugin name)
wrong:
```
plugins: [
  "@typescript-eslint",
  "tsdoc"
]
```
correct:
```
plugins: [
  "@typescript-eslint/eslint-plugin",
  "eslint-plugin-tsdoc"
]
```
ESLint plugins are referenced by their full package name (e.g., 'eslint-plugin-tsdoc') or their short name if prefixed with 'eslint-plugin-' (e.g., 'tsdoc'). The recommended approach is to use the full name for clarity or use a direct reference like this example.
tsdoc/syntax (rule name)
wrong:
```
rules: {
  "syntax": "warn"
}
```
correct:
```
rules: {
  "tsdoc/syntax": "warn"
}
```
ESLint rules from plugins must be prefixed with the plugin name or its alias, followed by a slash and the rule name. Omitting the prefix will result in the rule not being found.
ESLint Configuration Object
wrong:
```
export default {
  // ... config object ...
};
```
correct:
```
module.exports =  {
  // ... config object ...
};
```
ESLint configuration files (`.eslintrc.js`) are typically CommonJS modules and should use `module.exports`. While ESLint has experimental support for ESM config files, CJS is the standard and most compatible approach.

Quickstart

This quickstart demonstrates how to install `eslint-plugin-tsdoc` along with its peer dependencies and configure your `.eslintrc.js` file to enable the `tsdoc/syntax` rule for validating TSDoc comments in a TypeScript project.

npm install --save-dev eslint typescript @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint-plugin-tsdoc

// .eslintrc.js
module.exports =  {
  plugins: [
    "@typescript-eslint/eslint-plugin",
    "eslint-plugin-tsdoc"
  ],
  extends:  [
    'plugin:@typescript-eslint/recommended'
  ],
  parser:  '@typescript-eslint/parser',
  parserOptions: {
    project: "./tsconfig.json",
    tsconfigRootDir: __dirname,
    ecmaVersion: 2018,
    sourceType: "module"
  },
  rules: {
    "tsdoc/syntax": "warn"
  }
};

view raw JSON →