0
# Prettier Plugin JSDoc
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: prettier-plugin-jsdoc
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install prettier-plugin-jsdoc --save-dev`
10

11
## Core Imports
12

13
```typescript
14
import { options, parsers, defaultOptions } from "prettier-plugin-jsdoc";
15
import type { Options } from "prettier-plugin-jsdoc";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { options, parsers, defaultOptions } = require("prettier-plugin-jsdoc");
22
```
23

24
## Basic Usage
25

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

28
```json
29
{
30
  "plugins": ["prettier-plugin-jsdoc"],
31
  "jsdocSpaces": 1,
32
  "jsdocVerticalAlignment": false,
33
  "jsdocDescriptionWithDot": false
34
}
35
```
36

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

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

60
## Architecture
61

62
Prettier Plugin JSDoc operates through several key components:
63

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

70
## Capabilities
71

72
### Plugin Configuration
73

74
Core configuration options for customizing JSDoc formatting behavior.
75

76
```typescript { .api }
77
interface JsdocOptions {
78
  /** Number of spaces to separate tag elements (default: 1) */
79
  jsdocSpaces: number;
80
  /** Print width for JSDoc formatting, falls back to Prettier's printWidth */
81
  jsdocPrintWidth?: number;
82
  /** Add dot at the end of description (default: false) */
83
  jsdocDescriptionWithDot: boolean;
84
  /** Use description tag explicitly (default: false) */
85
  jsdocDescriptionTag: boolean;
86
  /** Align tags, types, names and description vertically (default: false) */
87
  jsdocVerticalAlignment: boolean;
88
  /** Keep indentation for unparseable examples (default: false) */
89
  jsdocKeepUnParseAbleExampleIndent: boolean;
90
  /** @deprecated Use jsdocCommentLineStrategy instead */
91
  jsdocSingleLineComment: boolean;
92
  /** Comment line handling strategy (default: "singleLine") */
93
  jsdocCommentLineStrategy: "singleLine" | "multiline" | "keep";
94
  /** Add space between last @param and @returns (default: false) */
95
  jsdocSeparateReturnsFromParam: boolean;
96
  /** Add space between tag groups (default: false) */
97
  jsdocSeparateTagGroups: boolean;
98
  /** Add default values to parameter descriptions (default: true) */
99
  jsdocAddDefaultToDescription: boolean;
100
  /** Capitalize first letter of description (default: true) */
101
  jsdocCapitalizeDescription: boolean;
102
  /** Use code fences instead of indentation for code blocks (default: false) */
103
  jsdocPreferCodeFences: boolean;
104
  /** Format as TSDoc instead of JSDoc (default: false) */
105
  tsdoc: boolean;
106
  /** Line wrapping strategy (default: "greedy") */
107
  jsdocLineWrappingStyle: "greedy";
108
  /** Custom tag ordering configuration */
109
  jsdocTagsOrder?: Record<string, number>;
110
}
111

112
type Options = Partial<JsdocOptions>;
113

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

117
/** Default values for all JSDoc options */
118
const defaultOptions: JsdocOptions;
119
```
120

121
### Enhanced Parsers
122

123
Enhanced versions of Prettier parsers with JSDoc processing capabilities.
124

125
```typescript { .api }
126
interface EnhancedParsers {
127
  /** Enhanced Babel parser for JavaScript */
128
  babel: prettier.Parser;
129
  /** Enhanced Babel parser for Flow syntax */
130
  "babel-flow": prettier.Parser;
131
  /** Enhanced Babel parser for TypeScript */
132
  "babel-ts": prettier.Parser;
133
  /** Enhanced Flow parser */
134
  flow: prettier.Parser;
135
  /** Enhanced TypeScript parser */
136
  typescript: prettier.Parser;
137
  /** @deprecated Backward compatible parser, use babel-ts instead */
138
  "jsdoc-parser": prettier.Parser;
139
}
140

141
/** Enhanced parsers with JSDoc processing capabilities */
142
const parsers: EnhancedParsers;
143
```
144

145
### Type Definitions
146

147
Core type definitions for JSDoc processing and Prettier integration.
148

149
```typescript { .api }
150
interface AllOptions extends ParserOptions, JsdocOptions {}
151

152
interface PrettierComment {
153
  type: "CommentBlock" | "Block";
154
  value: string;
155
  start: number;
156
  end: number;
157
  loc: {
158
    start: { line: number; column: number };
159
    end: { line: number; column: number };
160
  };
161
}
162

163
interface Token {
164
  type: "CommentBlock" | "Block" | {
165
    label: string;
166
    keyword?: string;
167
    beforeExpr: boolean;
168
    startsExpr: boolean;
169
    rightAssociative: boolean;
170
    isLoop: boolean;
171
    isAssign: boolean;
172
    prefix: boolean;
173
    postfix: boolean;
174
    binop: null;
175
  };
176
  value: string;
177
  start: number;
178
  end: number;
179
  loc: {
180
    start: { line: number; column: number };
181
    end: { line: number; column: number };
182
  };
183
}
184

185
interface AST {
186
  start: number;
187
  end: number;
188
  loc: {
189
    start: { line: number; column: number };
190
    end: { line: number; column: number };
191
  };
192
  errors: [];
193
  program: {
194
    type: "Program";
195
    start: number;
196
    end: number;
197
    loc: [];
198
    sourceType: "module";
199
    interpreter: null;
200
    body: [];
201
    directives: [];
202
  };
203
  comments: PrettierComment[];
204
  tokens: Token[];
205
}
206
```
207

208
### JSDoc Tag Support
209

210
Comprehensive support for standard JSDoc tags and formatting.
211

212
The plugin supports all standard JSDoc tags including:
213

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

223
**Tag Formatting Features:**
224

225
```typescript
226
// Input JSDoc with inconsistent formatting
227
/**
228
* @param {  String|Number   }    text  - description text
229
* @param { Object } [options={}] configuration options
230
* @returns {Promise<Boolean>} promise resolving to success status
231
*/
232

233
// Output after formatting with default options
234
/**
235
 * @param {string | number} text Description text
236
 * @param {object} [options={}] Configuration options
237
 * @returns {Promise<boolean>} Promise resolving to success status
238
 */
239
```
240

241
### Type Conversion
242

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

245
**Type Conversion Features:**
246

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

253
### Configuration Examples
254

255
**Minimal Configuration:**
256
```json
257
{
258
  "plugins": ["prettier-plugin-jsdoc"]
259
}
260
```
261

262
**Comprehensive Configuration:**
263
```json
264
{
265
  "plugins": ["prettier-plugin-jsdoc"],
266
  "jsdocSpaces": 1,
267
  "jsdocPrintWidth": 80,
268
  "jsdocDescriptionWithDot": true,
269
  "jsdocVerticalAlignment": true,
270
  "jsdocCommentLineStrategy": "multiline",
271
  "jsdocSeparateReturnsFromParam": true,
272
  "jsdocSeparateTagGroups": true,
273
  "jsdocCapitalizeDescription": true,
274
  "jsdocAddDefaultToDescription": true,
275
  "jsdocPreferCodeFences": true,
276
  "tsdoc": false,
277
  "jsdocTagsOrder": {
278
    "param": 1,
279
    "returns": 2,
280
    "example": 3
281
  }
282
}
283
```
284

285
**TypeScript/TSDoc Configuration:**
286
```json
287
{
288
  "plugins": ["prettier-plugin-jsdoc"],
289
  "tsdoc": true,
290
  "jsdocCommentLineStrategy": "multiline"
291
}
292
```
293

294
**File-specific Overrides:**
295
```json
296
{
297
  "plugins": ["prettier-plugin-jsdoc"],
298
  "overrides": [
299
    {
300
      "files": "*.tsx",
301
      "options": {
302
        "plugins": []
303
      }
304
    }
305
  ]
306
}
307
```