https://github.com/fardad-dev/prettier-plugin-jsdoc
A Prettier plugin to format JSDoc comments.
https://github.com/fardad-dev/prettier-plugin-jsdoc
Last synced: about 2 months ago
JSON representation
A Prettier plugin to format JSDoc comments.
- Host: GitHub
- URL: https://github.com/fardad-dev/prettier-plugin-jsdoc
- Owner: fardad-dev
- License: mit
- Created: 2020-04-05T12:28:22.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2026-05-09T17:01:02.000Z (about 2 months ago)
- Last Synced: 2026-05-13T22:39:32.480Z (about 2 months ago)
- Language: TypeScript
- Homepage:
- Size: 1.03 MB
- Stars: 271
- Watchers: 2
- Forks: 35
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://nodei.co/npm/prettier-plugin-jsdoc/)
[](https://packagephobia.now.sh/result?p=prettier-plugin-jsdoc)
# prettier-plugin-jsdoc
Prettier plugin for formatting comment blocks and converting to a standard.
Match with Visual Studio Code and other IDEs that support JSDoc and comments as Markdown.
Many good examples of how this plugin works are in the [`/tests`](/tests) directory.
Compare tests and their [snapshots](/tests//__snapshots__).
Configured with best practices of JSDoc style guides.
## Contents
- [Installation](#installation)
- [Configuration](#configuration)
- [Ignore](#ignore)
- [Examples](#examples)
- [Options](#options)
- [Supported Prettier versions](#supported-prettier-versions)
- [Contributing](#contributing)
- [Links](#links)
- [Acknowledge](#acknowledge)
## Installation
1. [Install](https://prettier.io/docs/en/install.html) and [configure](https://prettier.io/docs/en/configuration) Prettier
2. Install `prettier-plugin-jsdoc`:
```sh
npm install prettier-plugin-jsdoc --save-dev
```
```sh
yarn add prettier-plugin-jsdoc --dev
```
## Configuration
Add `prettier-plugin-jsdoc` to your `plugins` list.
**Important:** When using multiple plugins, add `prettier-plugin-jsdoc` to the **end** of the plugins list.
`.prettierrc`:
```json
{
"plugins": ["prettier-plugin-jsdoc"]
}
```
With other plugins:
```json
{
"plugins": [..., "prettier-plugin-jsdoc"]
}
```
`prettier.config.js`:
```js
export default {
plugins: ["prettier-plugin-jsdoc"],
};
```
If you want to ignore some types of files, use `overrides` with an empty `plugins`:
```json
{
"plugins": ["prettier-plugin-jsdoc"],
"overrides": [
{
"files": "*.tsx",
"options": {
"plugins": []
}
}
]
}
```
## Ignore
To prevent Prettier from formatting, use `/* */` or `//` instead of /\*\* \*/, or see [Ignoring Code](https://prettier.io/docs/en/ignore#javascript).
## Examples
#### Single line
```js
/**
* @param { string } param0 description
*/
function fun(param0) {}
```
Formats to:
```js
/** @param {string} param0 Description */
function fun(param0) {}
```
#### React component
```js
/**
* @type {React.FC<{ message:string} >}
*/
const Component = memo(({ message }) => {
return
{message}
;
});
```
Formats to:
```js
/** @type {React.FC<{message: string}>} */
const Component = memo(({ message }) => {
return
{message}
;
});
```
#### TypeScript objects
```js
/**
@typedef {
{
"userId": {
"profileImageLink": *,
"isBusinessUser": "isResellerUser"|"isBoolean"| "isSubUser" | "isNot",
"shareCode": number,
"referredBy": any,
},
id:number
}
} User
*/
```
Format to:
```js
/**
* @typedef {{
* userId: {
* profileImageLink: any;
* isBusinessUser: "isResellerUser" | "isBoolean" | "isSubUser" | "isNot";
* shareCode: number;
* referredBy: any;
* };
* id: number;
* }} User
*/
```
#### Example
Add code to `@examples` tag.
```js
/**
* @examples
* var one= 5
* var two=10
*
* if(one > 2) { two += one }
*/
```
Formats to:
```js
/**
* @example
* var one = 5;
* var two = 10;
*
* if (one > 2) {
* two += one;
* }
*/
```
#### Description
`@description` is formatted as Markdown so that you can use any features of Markdown on that.
Like code tags (` ```js `), header tags like `# Header`, or other Markdown features.
## Options
| Key | Type | Default | Description |
| :---------------------------------- | :-------------------------------- | :----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jsdocSpaces` | Number | 1 |
| `jsdocDescriptionWithDot` | Boolean | false |
| `jsdocDescriptionTag` | Boolean | false |
| `jsdocVerticalAlignment` | Boolean | false |
| `jsdocKeepUnParseAbleExampleIndent` | Boolean | false |
| `jsdocCommentLineStrategy` | ("singleLine","multiline","keep") | "singleLine" |
| `jsdocCapitalizeDescription` | Boolean | true |
| `jsdocSeparateReturnsFromParam` | Boolean | false | Adds a space between last `@param` and `@returns` |
| `jsdocSeparateTagGroups` | Boolean | false | Adds a space between tag groups |
| `jsdocPreferCodeFences` | Boolean | false | Always fence code blocks (surround them by triple backticks) |
| `jsdocEmptyCommentStrategy` | ("remove","keep") | "remove" | How to handle empty JSDoc comment blocks |
| `jsdocBracketSpacing` | Boolean | false | Whether to add spaces inside JSDoc type brackets. `{string}` (false) vs `{ string }` (true) |
| `tsdoc` | Boolean | false | See [TSDoc](#tsdoc) |
| `jsdocPrintWidth` | Number | undefined | If you don't set the value to `jsdocPrintWidth`, `printWidth` will be used as `jsdocPrintWidth` |
| `jsdocLineWrappingStyle` | String | "greedy" | "greedy": lines wrap as soon as they reach `printWidth`. "balance": preserve existing line breaks if lines are shorter than `printWidth`, otherwise use greedy wrapping |
| `jsdocTagsOrder` | String (object) | undefined | See [Custom Tags Order](doc/CUSTOM_TAGS_ORDER.md) |
### TSDoc
We hope to support the whole [TSDoc](https://tsdoc.org/).
If we missed something, please [create an issue](https://github.com/hosseinmd/prettier-plugin-jsdoc/issues/new).
To enable, add:
```json
{
"tsdoc": true
}
```
## Supported Prettier versions
| Plugin version | Prettier version |
| -------------- | ---------------- |
| 1.0.0+ | 3.0.0+ |
| 0.4.2 | 2.x+ |
## Contributing
1. Fork and clone the repository
2. [Install Yarn](https://yarnpkg.com/getting-started/install)
3. Install project dependencies:
```sh
yarn install
```
4. Make changes and make sure that tests pass:
```js
yarn run test
```
5. Update or add tests to your changes if needed
6. Create PR
## Links
- [Prettier](https://prettier.io)
- [JSDoc](https://jsdoc.app)
## Acknowledge
This project extended from the @gum3n worked project on GitLab.