or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configurations.mdindex.mdprocessor.mdrules.md
tile.json

tessl/npm-eslint-plugin-jsdoc

JSDoc linting rules for ESLint with comprehensive validation and configuration options.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/eslint-plugin-jsdoc@54.3.x

To install, run

npx @tessl/cli install tessl/npm-eslint-plugin-jsdoc@54.3.0

index.mddocs/

ESLint Plugin JSDoc

ESLint Plugin JSDoc provides comprehensive JSDoc linting rules for ESLint that enforce documentation standards and best practices in JavaScript and TypeScript projects. It offers 57 linting rules to validate JSDoc comments including parameter descriptions, return types, example code syntax, and proper formatting, with extensive configuration options for teams requiring consistent documentation standards.

Package Information

  • Package Name: eslint-plugin-jsdoc
  • Package Type: npm
  • Language: JavaScript with TypeScript support
  • Installation: npm install eslint-plugin-jsdoc

Core Imports

ESM (ES modules):

import jsdocPlugin from "eslint-plugin-jsdoc";

CommonJS:

const jsdocPlugin = require("eslint-plugin-jsdoc");

Basic Usage

ESLint Flat Config (Modern)

import jsdocPlugin from "eslint-plugin-jsdoc";

export default [
  {
    plugins: {
      jsdoc: jsdocPlugin,
    },
    rules: {
      "jsdoc/require-jsdoc": "error",
      "jsdoc/require-param": "error",
      "jsdoc/require-returns": "error",
    },
  },
  // Use a predefined configuration
  jsdocPlugin.configs["flat/recommended"],
];

Legacy ESLint Config (.eslintrc)

{
  "plugins": ["jsdoc"],
  "extends": ["plugin:jsdoc/recommended"],
  "rules": {
    "jsdoc/require-jsdoc": "error"
  }
}

TypeScript Projects

import jsdocPlugin from "eslint-plugin-jsdoc";

export default [
  jsdocPlugin.configs["flat/recommended-typescript"],
  {
    rules: {
      "jsdoc/require-param-type": "off", // TypeScript provides types
      "jsdoc/require-returns-type": "off"
    }
  }
];

Architecture

ESLint Plugin JSDoc is built around several key components:

  • Rules Engine: 57 individual ESLint rules covering all aspects of JSDoc validation
  • Configuration System: Multiple predefined configurations for different use cases (recommended, TypeScript, stylistic)
  • Processor Plugin: Special processor for validating JSDoc examples and default values as executable code
  • Type System Integration: Full TypeScript support with TypeScript-specific rule variants
  • Tag Management: Comprehensive tag validation with support for custom tags and different JSDoc modes

Capabilities

Linting Rules

Complete set of 57 ESLint rules for validating JSDoc comments, covering syntax, content, formatting, and semantic correctness.

// Plugin object with rules property
interface ESLintPluginJSDoc {
  rules: {
    [ruleName: string]: ESLintRule;
  };
  configs: {
    [configName: string]: ESLintConfig;
  };
}

// Individual rule structure
interface ESLintRule {
  meta: {
    type: "problem" | "suggestion" | "layout";
    docs: {
      description: string;
      category: string;
      recommended: boolean;
    };
    schema: JSONSchema7;
  };
  create(context: ESLintRuleContext): ESLintVisitors;
}

Linting Rules

Predefined Configurations

Ready-to-use ESLint configurations for common JSDoc validation scenarios, including TypeScript-specific and stylistic variants.

interface ESLintConfig {
  plugins?: string[] | { [pluginName: string]: ESLintPlugin };
  rules: {
    [ruleName: string]: ESLintRuleConfig;
  };
  name?: string;
}

type ESLintRuleConfig = "off" | "warn" | "error" | 
  ["off" | "warn" | "error", ...any[]];

Configurations

JSDoc Processor

Advanced processor plugin for validating JSDoc example code and default expressions as executable JavaScript/TypeScript.

interface JsdocProcessorOptions {
  captionRequired?: boolean;
  paddedIndent?: number;
  checkDefaults?: boolean;
  checkParams?: boolean;
  checkExamples?: boolean;
  checkProperties?: boolean;
  matchingFileName?: string;
  matchingFileNameDefaults?: string;
  matchingFileNameParams?: string;
  matchingFileNameProperties?: string;
  exampleCodeRegex?: string | RegExp;
  rejectExampleCodeRegex?: string | RegExp;
  allowedLanguagesToProcess?: string[];
  sourceType?: "script" | "module";
  parser?: ESLintParser;
}

function getJsdocProcessorPlugin(options?: JsdocProcessorOptions): ESLintPlugin;

JSDoc Processor

Rule Development Utilities

Internal utilities for building custom JSDoc ESLint rules (advanced usage).

// Core rule builder function
function iterateJsdoc(
  iterator: RuleIterator,
  ruleConfig: RuleConfig
): ESLintRule;

// Additional utility exports
interface UtilityExports {
  parseComment: (comment: Comment) => JsdocBlock;
}

These utilities are primarily intended for plugin developers who need to create custom JSDoc rules.

Types

interface ESLintPlugin {
  meta: {
    name: string;
    version: string;
  };
  rules?: { [ruleName: string]: ESLintRule };
  configs?: { [configName: string]: ESLintConfig };
  processors?: { [processorName: string]: ESLintProcessor };
}

interface ESLintRuleContext {
  getSourceCode(): SourceCode;
  report(descriptor: ReportDescriptor): void;
  options: any[];
  settings: { [name: string]: any };
}

interface ReportDescriptor {
  node: ESTreeNode;
  message: string;
  data?: { [key: string]: string };
  fix?: (fixer: RuleFixer) => Fix | Fix[] | null;
}

type ESLintVisitors = {
  [nodeType: string]: (node: ESTreeNode) => void;
};