or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-prettier-plugin-jsdoc

A Prettier plugin to format JSDoc comments.

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/prettier-plugin-jsdoc@1.3.x

To install, run

npx @tessl/cli install tessl/npm-prettier-plugin-jsdoc@1.3.0

Prettier Plugin JSDoc

Prettier Plugin JSDoc is a Prettier plugin that automatically formats JSDoc comments according to standard practices and best practices of JSDoc style guides. It integrates seamlessly with Prettier's formatting pipeline to standardize JSDoc documentation blocks, supporting TypeScript type annotations, React component documentation, and extensive configuration options for spacing, alignment, and formatting.

Package Information

Package Name: prettier-plugin-jsdoc
Package Type: npm
Language: TypeScript
Installation: npm install prettier-plugin-jsdoc --save-dev

Core Imports

import { options, parsers, defaultOptions } from "prettier-plugin-jsdoc";
import type { Options } from "prettier-plugin-jsdoc";

For CommonJS:

const { options, parsers, defaultOptions } = require("prettier-plugin-jsdoc");

Basic Usage

The plugin is typically used through Prettier configuration rather than direct imports:

{
  "plugins": ["prettier-plugin-jsdoc"],
  "jsdocSpaces": 1,
  "jsdocVerticalAlignment": false,
  "jsdocDescriptionWithDot": false
}

// Example JSDoc that will be formatted
/**
* function example description that was wrapped by hand
* so it have more then one line and don't end with a dot
* @return {Boolean} Description for @returns with s  
* @param {String|Number} text - some text description that is very long and needs to be wrapped
* @param {String} [defaultValue="defaultTest"] TODO
*/
const testFunction = (text, defaultValue) => true;

// After formatting:
/**
 * Function example description that was wrapped by hand so it have more then
 * one line and don't end with a dot.
 * @param {string | number} text Some text description that is very long and
 *   needs to be wrapped
 * @param {string} [defaultValue="defaultTest"] TODO
 * @returns {boolean} Description for @returns with s
 */
const testFunction = (text, defaultValue) => true;

Architecture

Prettier Plugin JSDoc operates through several key components:

Parser Enhancement: Wraps existing Prettier parsers (Babel, Flow, TypeScript) to add JSDoc processing capabilities
Comment Detection: Identifies JSDoc comment blocks using pattern matching
JSDoc Parsing: Uses comment-parser to parse JSDoc syntax and structure
Formatting Engine: Applies formatting rules based on configuration options
Integration Layer: Seamlessly integrates with Prettier's formatting pipeline

Capabilities

Plugin Configuration

Core configuration options for customizing JSDoc formatting behavior.

interface JsdocOptions {
  /** Number of spaces to separate tag elements (default: 1) */
  jsdocSpaces: number;
  /** Print width for JSDoc formatting, falls back to Prettier's printWidth */
  jsdocPrintWidth?: number;
  /** Add dot at the end of description (default: false) */
  jsdocDescriptionWithDot: boolean;
  /** Use description tag explicitly (default: false) */
  jsdocDescriptionTag: boolean;
  /** Align tags, types, names and description vertically (default: false) */
  jsdocVerticalAlignment: boolean;
  /** Keep indentation for unparseable examples (default: false) */
  jsdocKeepUnParseAbleExampleIndent: boolean;
  /** @deprecated Use jsdocCommentLineStrategy instead */
  jsdocSingleLineComment: boolean;
  /** Comment line handling strategy (default: "singleLine") */
  jsdocCommentLineStrategy: "singleLine" | "multiline" | "keep";
  /** Add space between last @param and @returns (default: false) */
  jsdocSeparateReturnsFromParam: boolean;
  /** Add space between tag groups (default: false) */
  jsdocSeparateTagGroups: boolean;
  /** Add default values to parameter descriptions (default: true) */
  jsdocAddDefaultToDescription: boolean;
  /** Capitalize first letter of description (default: true) */
  jsdocCapitalizeDescription: boolean;
  /** Use code fences instead of indentation for code blocks (default: false) */
  jsdocPreferCodeFences: boolean;
  /** Format as TSDoc instead of JSDoc (default: false) */
  tsdoc: boolean;
  /** Line wrapping strategy (default: "greedy") */
  jsdocLineWrappingStyle: "greedy";
  /** Custom tag ordering configuration */
  jsdocTagsOrder?: Record<string, number>;
}

type Options = Partial<JsdocOptions>;

/** Configuration options object for Prettier integration */
const options: Record<keyof JsdocOptions, SupportOption>;

/** Default values for all JSDoc options */
const defaultOptions: JsdocOptions;

Enhanced Parsers

Enhanced versions of Prettier parsers with JSDoc processing capabilities.

interface EnhancedParsers {
  /** Enhanced Babel parser for JavaScript */
  babel: prettier.Parser;
  /** Enhanced Babel parser for Flow syntax */
  "babel-flow": prettier.Parser;
  /** Enhanced Babel parser for TypeScript */
  "babel-ts": prettier.Parser;
  /** Enhanced Flow parser */
  flow: prettier.Parser;
  /** Enhanced TypeScript parser */
  typescript: prettier.Parser;
  /** @deprecated Backward compatible parser, use babel-ts instead */
  "jsdoc-parser": prettier.Parser;
}

/** Enhanced parsers with JSDoc processing capabilities */
const parsers: EnhancedParsers;

Type Definitions

Core type definitions for JSDoc processing and Prettier integration.

interface AllOptions extends ParserOptions, JsdocOptions {}

interface PrettierComment {
  type: "CommentBlock" | "Block";
  value: string;
  start: number;
  end: number;
  loc: {
    start: { line: number; column: number };
    end: { line: number; column: number };
  };
}

interface Token {
  type: "CommentBlock" | "Block" | {
    label: string;
    keyword?: string;
    beforeExpr: boolean;
    startsExpr: boolean;
    rightAssociative: boolean;
    isLoop: boolean;
    isAssign: boolean;
    prefix: boolean;
    postfix: boolean;
    binop: null;
  };
  value: string;
  start: number;
  end: number;
  loc: {
    start: { line: number; column: number };
    end: { line: number; column: number };
  };
}

interface AST {
  start: number;
  end: number;
  loc: {
    start: { line: number; column: number };
    end: { line: number; column: number };
  };
  errors: [];
  program: {
    type: "Program";
    start: number;
    end: number;
    loc: [];
    sourceType: "module";
    interpreter: null;
    body: [];
    directives: [];
  };
  comments: PrettierComment[];
  tokens: Token[];
}

JSDoc Tag Support

Comprehensive support for standard JSDoc tags and formatting.

The plugin supports all standard JSDoc tags including:

Documentation tags: @description, @example, @see, @since, @version, @author, @license
Parameter tags: @param, @returns, @yields, @throws
Type tags: @type, @typedef, @callback, @template
Structure tags: @class, @namespace, @module, @memberof, @property
Behavior tags: @abstract, @async, @override, @deprecated, @ignore
Access tags: @private, @constant, @default
Inheritance tags: @extends, @augments, @borrows
Special tags: @file, @provides-module, @satisfies

Tag Formatting Features:

// Input JSDoc with inconsistent formatting
/**
* @param {  String|Number   }    text  - description text
* @param { Object } [options={}] configuration options
* @returns {Promise<Boolean>} promise resolving to success status
*/

// Output after formatting with default options
/**
 * @param {string | number} text Description text
 * @param {object} [options={}] Configuration options
 * @returns {Promise<boolean>} Promise resolving to success status
 */

Type Conversion

Automatic conversion of JSDoc type syntax to modern TypeScript-compatible syntax.

Type Conversion Features:

JSDoc generics (Foo.<Arg1, Arg2>) → TypeScript generics (Foo<Arg1, Arg2>)
Wildcard types (*) → TypeScript any (any)
Nullable types (?Type or Type?) → Union types (Type | null)
Array syntax (Array<Type>) → Array notation (Type[])
Type union normalization with proper spacing

Configuration Examples

Minimal Configuration:

{
  "plugins": ["prettier-plugin-jsdoc"]
}

Comprehensive Configuration:

{
  "plugins": ["prettier-plugin-jsdoc"],
  "jsdocSpaces": 1,
  "jsdocPrintWidth": 80,
  "jsdocDescriptionWithDot": true,
  "jsdocVerticalAlignment": true,
  "jsdocCommentLineStrategy": "multiline",
  "jsdocSeparateReturnsFromParam": true,
  "jsdocSeparateTagGroups": true,
  "jsdocCapitalizeDescription": true,
  "jsdocAddDefaultToDescription": true,
  "jsdocPreferCodeFences": true,
  "tsdoc": false,
  "jsdocTagsOrder": {
    "param": 1,
    "returns": 2,
    "example": 3
  }
}

TypeScript/TSDoc Configuration:

{
  "plugins": ["prettier-plugin-jsdoc"],
  "tsdoc": true,
  "jsdocCommentLineStrategy": "multiline"
}

File-specific Overrides:

{
  "plugins": ["prettier-plugin-jsdoc"],
  "overrides": [
    {
      "files": "*.tsx",
      "options": {
        "plugins": []
      }
    }
  ]
}