eslint-plugin-meaningful-docs

ESLint plugin to detect and auto-fix AI-generated documentation patterns in TypeScript/JavaScript codebases.

AI code agents generate excessive, redundant documentation that clutters codebases. This plugin catches common patterns and helps keep your docs meaningful.

Installation

npm install eslint-plugin-meaningful-docs --save-dev

Usage

Flat Config (ESLint 9+)

// eslint.config.js
import meaningfulDocs from 'eslint-plugin-meaningful-docs';

export default [
  // Use the recommended config
  meaningfulDocs.configs.recommended,

  // Or configure rules individually
  {
    plugins: {
      'meaningful-docs': meaningfulDocs,
    },
    rules: {
      'meaningful-docs/no-obvious-comments': 'warn',
      'meaningful-docs/no-ai-filler-phrases': 'warn',
      'meaningful-docs/no-redundant-function-description': 'warn',
      'meaningful-docs/no-redundant-type-docs': 'warn',
      'meaningful-docs/no-over-documented-simple-code': 'warn',
      'meaningful-docs/no-restating-comments': 'warn',
      'meaningful-docs/no-redundant-jsdoc-params': 'warn',
    },
  },
];

Rules

no-obvious-comments

Detects comments that state the obvious and add no value.

// BAD
// Loop through items
for (const item of items) { }

// Increment counter
counter++;

// GOOD - no comment needed, code is self-explanatory
for (const item of items) { }
counter++;

Auto-fixable: Yes - removes the comment

Options:

• patterns (string[]): Additional regex patterns to flag

no-ai-filler-phrases

Detects AI-style filler language in comments.

// BAD
/** This function retrieves the user from the database */
function getUser() {}

// Note that we call the API here
fetch('/api');

// GOOD
/** Retrieves from read replica, falls back to primary on miss */
function getUser() {}

Auto-fixable: Partially - removes entirely filler comments

Options:

• phrases (string[]): Additional filler phrases to detect

no-redundant-function-description

Detects JSDoc descriptions that merely restate the function name.

// BAD
/** Gets user data */
function getUserData() {}

/** Calculates the total */
function calculateTotal() {}

// GOOD
/** Fetches from cache first, retries 3x on failure */
function getUserData() {}

/** Includes tax and shipping per GAAP requirements */
function calculateTotal() {}

Auto-fixable: Yes - removes redundant description

no-redundant-type-docs

Detects @param and @returns tags that merely restate TypeScript types.

// BAD
/**
 * @param userId - The user ID
 * @returns The user
 */
function getUser(userId: string): User {}

// GOOD - let TypeScript handle type documentation
function getUser(userId: string): User {}

// ALSO GOOD - adds meaningful context
/**
 * @param userId - Must be a v4 UUID from the auth service
 */
function getUser(userId: string): User {}

Auto-fixable: No (requires judgment on what to keep)

Options:

• allowDescriptiveParams (boolean, default: true): Keep @param if it adds context beyond the type

no-over-documented-simple-code

Detects excessive documentation on trivial code.

// BAD
/**
 * Gets the current value from the store.
 * This function retrieves the value.
 * It returns the value as-is.
 * @returns The value
 */
function getValue() {
  return 1;
}

// GOOD
function getValue() {
  return 1;
}

Auto-fixable: No (requires human judgment)

Options:

• maxSimpleStatements (number, default: 1): Max statements for "simple" code
• maxDocLines (number, default: 3): Max JSDoc lines for simple code

no-restating-comments

Detects comments that simply restate what the code does.

// BAD
// Check if user is valid
if (user.isValid) { }

// Return the result
return result;

// Loop through items
for (const item of items) { }

// GOOD - no comment needed, or explain WHY
// Validation required before API call (see SEC-123)
if (user.isValid) { }

Auto-fixable: Yes - removes the comment

Options:

• threshold (number, 0-1, default: 0.4): Word overlap threshold for detection

no-redundant-jsdoc-params

Removes @param and @returns tags when TypeScript types already document the parameters.

// BAD - TypeScript types already document this
/**
 * @param userId - The user ID
 * @param options - The options
 * @returns The user object
 */
function getUser(userId: string, options: Options): User {}

// GOOD - let TypeScript be the documentation
function getUser(userId: string, options: Options): User {}

// ALSO GOOD - untyped params still need @param
/**
 * @param callback - Called when complete
 */
function fetchData(url: string, callback): void {}

Auto-fixable: Yes - removes redundant tags

Preserved Patterns

The plugin is smart about preserving valuable documentation. It will NOT flag comments containing:

• Why explanations: "because", "due to", "workaround", "edge case"
• Task markers: "TODO", "FIXME", "BUG", "HACK", "XXX"
• Business context: "requirement", "compliance", "legacy", "specification"
• Warnings: "warning", "caution", "security", "throws", "side effect"

Configs

recommended

Enables all rules at warn level:

import meaningfulDocs from 'eslint-plugin-meaningful-docs';

export default [
  meaningfulDocs.configs.recommended,
];

strict

Enables all rules at error level:

import meaningfulDocs from 'eslint-plugin-meaningful-docs';

export default [
  meaningfulDocs.configs.strict,
];

Running with Auto-fix

# Check for issues
npx eslint src/

# Auto-fix where possible
npx eslint src/ --fix

CI/Pre-commit Integration

Add to your package.json:

{
  "scripts": {
    "lint": "eslint src/",
    "lint:fix": "eslint src/ --fix"
  }
}

Or use with lint-staged:

{
  "lint-staged": {
    "*.{ts,tsx,js,jsx}": "eslint --fix"
  }
}

License

MIT