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

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

Usage

$3

`js
// 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

$3

Detects comments that state the obvious and add no value.

`js
// 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

$3

Detects AI-style filler language in comments.

`js
// 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

$3

Detects JSDoc descriptions that merely restate the function name.

`js
// 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

$3

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

`ts
// 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

$3

Detects excessive documentation on trivial code.

`js
// 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

$3

Detects comments that simply restate what the code does.

`js
// 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

$3

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

`ts
// 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

$3

Enables all rules at warn level:

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

export default [
meaningfulDocs.configs.recommended,
];
`

$3

Enables all rules at error level:

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

export default [
meaningfulDocs.configs.strict,
];
`

Running with Auto-fix

`bash


Check for issues

npx eslint src/

Auto-fix where possible

npx eslint src/ --fix
`

CI/Pre-commit Integration

Add to your package.json:

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

Or use with lint-staged:

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

License

MIT