JSDoc
An ESLint plugin providing linting rules to enforce consistent and valid JSDoc comments in JavaScript and TypeScript code.
What is JSDoc?
eslint-plugin-jsdoc is an ESLint plugin that provides a comprehensive set of linting rules specifically for JSDoc comments in JavaScript and TypeScript code. It helps developers enforce consistent and valid documentation by checking for errors in tag usage, type definitions, formatting, and completeness. The plugin solves the problem of inconsistent or incorrect JSDoc comments, which can lead to poor documentation quality and reduced tooling effectiveness.
JavaScript and TypeScript developers who use JSDoc for code documentation and want to enforce consistency and correctness automatically through linting. It is particularly useful for teams working on large codebases or projects where maintaining documentation standards is critical.
Developers choose eslint-plugin-jsdoc because it offers a specialized, highly configurable set of rules tailored for JSDoc, integrates seamlessly with ESLint, and includes auto-fix capabilities for many issues. It provides pre-configured rulesets for different environments (e.g., TypeScript, TSDoc), reducing setup time and ensuring best practices.
Overview
JSDoc specific linting rules for ESLint.
Use Cases
Best For
- Enforcing consistent JSDoc formatting across a team's codebase
- Validating JSDoc types and tag usage in TypeScript projects
- Automatically checking for missing parameter documentation in functions
- Ensuring JSDoc comments adhere to project-specific style guides
- Integrating JSDoc linting into CI/CD pipelines for quality assurance
- Migrating legacy codebases to standardized JSDoc practices
Not Ideal For
- Projects that have fully adopted TypeScript and rely solely on its native type annotations without any JSDoc comments
- Teams using lightweight or alternative documentation tools like documentation.js that don't require strict linting enforcement
- Environments where ESLint is not integrated or cannot be used due to tooling or policy constraints
- Small, informal codebases where manual documentation review is sufficient and automated linting would add unnecessary overhead
Pros & Cons
Pros
Offers over 50 specialized rules covering tag validation, type checking, consistency, and completeness, as detailed in the extensive rules table in the README.
Many rules support ESLint's auto-fix feature, automatically correcting issues like asterisk alignment and missing tags, reducing manual cleanup effort.
Provides pre-configured rulesets for TypeScript syntax and TSDoc, including 'flat/recommended-typescript' and 'flat/recommended-tsdoc', ensuring seamless integration with modern JavaScript ecosystems.
Supports multiple configuration methods (flat config and eslintrc) with granular rulesets, allowing teams to tailor linting to project-specific styles and requirements.
Cons
The README outlines multiple configuration approaches (flat config procedural/declarative, eslintrc), which can be overwhelming for users new to ESLint or JSDoc linting.
Some rules like 'check-examples' are deprecated, and granular configs exclude certain rules (e.g., 'require-description' is omitted for being 'too demanding'), indicating potential maintenance challenges or over-aggressiveness.
Enabling numerous rules, especially on large codebases, can add significant linting time, potentially slowing down development and CI/CD pipelines.
Frequently Asked Questions
Related Projects
Tailwind CSSESLint plugin for Tailwind CSS usage
eslint-plugin-graphql:vertical_traffic_light: Check your GraphQL query strings against a schema.
graphql-eslintESLint parser, plugin, and rule set for GraphQL (for schema and operations). Easily customizable with custom rules. Integrates with IDEs and modern GraphQL tools.
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.