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 directory.
Compare tests and their snapshots.

Configured with best practices of JSDoc style guides.

Contents

- Installation
- Configuration
- Ignore
- Examples
- Options
- Supported Prettier versions
- Contributing
- Links
- Acknowledge

Installation

1. Install and configure 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.

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 |
| 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 |

$3

We hope to support the whole TSDoc.
If we missed something, please create an issue.

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
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
- JSDoc

Acknowledge

This project extended from the @gum3n worked project on GitLab.