The JSDoc processor plugin enables validation of JSDoc example code and default expressions as executable JavaScript/TypeScript, ensuring that documentation examples are syntactically correct and properly formatted.
Creates a processor plugin for validating JSDoc examples and default values.
/**
* Creates a JSDoc processor plugin with optional configuration
* @param options - Configuration options for the processor
* @returns ESLint plugin with processor capabilities
*/
function getJsdocProcessorPlugin(options?: JsdocProcessorOptions): ESLintPlugin;
interface JsdocProcessorOptions {
/** Require captions for example tags */
captionRequired?: boolean;
/** Padding indentation for processed code */
paddedIndent?: number;
/** Check default values in @default tags */
checkDefaults?: boolean;
/** Check parameter defaults in @param tags */
checkParams?: boolean;
/** Check example code in @example tags (default: true) */
checkExamples?: boolean;
/** Check property defaults in @property tags */
checkProperties?: boolean;
/** Custom filename pattern for examples */
matchingFileName?: string;
/** Custom filename pattern for defaults */
matchingFileNameDefaults?: string;
/** Custom filename pattern for params */
matchingFileNameParams?: string;
/** Custom filename pattern for properties */
matchingFileNameProperties?: string;
/** Regex for matching example code */
exampleCodeRegex?: string | RegExp;
/** Regex for rejecting example code */
rejectExampleCodeRegex?: string | RegExp;
/** Allowed languages to process (default: ['js', 'ts', 'javascript', 'typescript']) */
allowedLanguagesToProcess?: string[];
/** Source type for parsing (default: "module") */
sourceType?: "script" | "module";
/** Custom ESLint parser */
parser?: ESLintParser;
}Usage Examples:
import { getJsdocProcessorPlugin } from "eslint-plugin-jsdoc/getJsdocProcessorPlugin.js";
// Basic processor for examples
const exampleProcessor = getJsdocProcessorPlugin();
// Advanced processor configuration
const advancedProcessor = getJsdocProcessorPlugin({
checkDefaults: true,
checkParams: true,
checkProperties: true,
captionRequired: true,
allowedLanguagesToProcess: ['js', 'ts', 'jsx', 'tsx']
});
export default [
{
plugins: {
examples: exampleProcessor
},
processor: "examples/examples"
}
];Validates JSDoc @example tags as executable code with full ESLint rule support.
interface ExampleProcessing {
/** File patterns for example processing */
files: string[];
/** Processor name */
processor: "examples/examples";
/** Rules specific to example code */
rules: {
[ruleName: string]: ESLintRuleConfig;
};
}Usage Examples:
/**
* Adds two numbers
* @example
* const result = add(5, 3);
* console.log(result); // 8
*
* @example
* // With destructuring
* const { add } = require('./math');
* add(10, 20); // 30
*/
function add(a, b) {
return a + b;
}Validates default expressions in JSDoc tags as executable JavaScript expressions.
interface DefaultProcessing {
/** Enable default value checking */
checkDefaults: boolean;
/** Enable parameter default checking */
checkParams: boolean;
/** Enable property default checking */
checkProperties: boolean;
}Usage Examples:
/**
* Configuration object
* @typedef {Object} Config
* @property {string} [name="defaultName"] - The name
* @property {number} [timeout=5000] - Timeout in milliseconds
* @property {boolean} [enabled=true] - Whether enabled
*/
/**
* Process data with options
* @param {Array} data - Input data
* @param {Object} [options={}] - Processing options
* @param {number} [options.limit=100] - Maximum items to process
*/
function processData(data, options = {}) {
// Implementation
}Controls which languages are processed for example validation.
interface LanguageSupport {
/** Languages to process (default: ['js', 'ts', 'javascript', 'typescript']) */
allowedLanguagesToProcess: string[];
/** Source type for parsing */
sourceType: "script" | "module";
/** Custom parser for specific languages */
parser?: ESLintParser;
}Usage Examples:
// Process only TypeScript examples
const tsProcessor = getJsdocProcessorPlugin({
allowedLanguagesToProcess: ['ts', 'typescript'],
sourceType: 'module'
});
// Multi-language support
const multiProcessor = getJsdocProcessorPlugin({
allowedLanguagesToProcess: ['js', 'ts', 'jsx', 'tsx']
});Advanced filtering capabilities for example code processing.
interface CodeFiltering {
/** Regex to match specific example code */
exampleCodeRegex?: string | RegExp;
/** Regex to reject specific example code */
rejectExampleCodeRegex?: string | RegExp;
/** Require captions for examples */
captionRequired?: boolean;
}Usage Examples:
// Only process examples with specific patterns
const filteredProcessor = getJsdocProcessorPlugin({
exampleCodeRegex: /^(?!.*console\.log).*$/, // Exclude console.log
captionRequired: true
});
/**
* Math utility
* @example
* <caption>Basic addition</caption>
* const result = add(2, 3);
* // result === 5
*/
function add(a, b) {
return a + b;
}Modern ESLint flat config setup with processor.
// Complete processor configuration
interface ProcessorConfig {
plugins: {
examples: ESLintPlugin;
};
processor: "examples/examples";
files?: string[];
rules?: {
[ruleName: string]: ESLintRuleConfig;
};
}Usage Examples:
import jsdocPlugin from "eslint-plugin-jsdoc";
import { getJsdocProcessorPlugin } from "eslint-plugin-jsdoc/getJsdocProcessorPlugin.js";
export default [
// Regular JSDoc rules
jsdocPlugin.configs["flat/recommended"],
// Example processor
{
files: ["**/*.js"],
plugins: {
examples: getJsdocProcessorPlugin()
},
processor: "examples/examples"
},
// Rules for processed examples
{
files: ["**/*.md/*.js"],
rules: {
"no-console": "off",
"no-unused-vars": "off",
"eol-last": "off"
}
}
];Ready-to-use processor configurations from the main plugin.
interface ProcessorConfigurations {
/** Basic example processing */
examples: ESLintConfig[];
/** Default expression processing */
"default-expressions": ESLintConfig[];
/** Combined processing */
"examples-and-default-expressions": ESLintConfig[];
}Usage Examples:
import jsdocPlugin from "eslint-plugin-jsdoc";
// Use predefined example configuration
export default [
...jsdocPlugin.configs.examples
];
// Use combined configuration
export default [
...jsdocPlugin.configs["examples-and-default-expressions"]
];The processor provides detailed error reporting for invalid example code and default expressions.
Example Error Messages:
@example error (no-unused-vars): 'unusedVar' is defined but never used
@example warning (no-console): Unexpected console statement
@default error - Caption is expected for examplesinterface ESLintProcessor {
meta: {
name: string;
version: string;
};
preprocess(text: string, filename: string): (string | ProcessorFile)[];
postprocess(messages: LintMessage[][], filename: string): LintMessage[];
supportsAutofix?: boolean;
}
interface ProcessorFile {
text: string;
filename: string;
}
interface LintMessage {
ruleId: string | null;
severity: 1 | 2;
message: string;
line: number;
column: number;
nodeType: string;
source: string;
endLine?: number;
endColumn?: number;
fix?: EditInfo;
}
interface ESLintParser {
parseForESLint(text: string, options: ParserOptions): {
ast: ESTreeNode;
services?: ParserServices;
scopeManager?: ScopeManager;
visitorKeys?: VisitorKeys;
};
}