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:

npm install prettier-plugin-jsdoc --save-dev

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:

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

With other plugins:

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

prettier.config.js:

export default {
  plugins: ["prettier-plugin-jsdoc"],
};

If you want to ignore some types of files, use overrides with an empty plugins:

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

/**
 * @param {  string   }    param0 description
 */
function fun(param0) {}

Formats to:

/** @param {string} param0 Description */
function fun(param0) {}

React component

/**
 * @type {React.FC<{   message:string}   >}
 */
const Component = memo(({ message }) => {
  return <p>{message}</p>;
});

Formats to:

/** @type {React.FC<{message: string}>} */
const Component = memo(({ message }) => {
  return <p>{message}</p>;
});

TypeScript objects

/**
 @typedef {
    {
        "userId": {
        "profileImageLink": *,
        "isBusinessUser": "isResellerUser"|"isBoolean"|  "isSubUser" |    "isNot",
        "shareCode": number,
        "referredBy": any,
        },
        id:number
      }
     } User
     */

Format to:

/**
 * @typedef {{
 *   userId: {
 *     profileImageLink: any;
 *     isBusinessUser: "isResellerUser" | "isBoolean" | "isSubUser" | "isNot";
 *     shareCode: number;
 *     referredBy: any;
 *   };
 *   id: number;
 * }} User
 */

Example

Add code to @examples tag.

/**
 * @examples
 *   var one= 5
 *   var two=10
 *
 *   if(one > 2) { two += one }
 */

Formats to:

/**
 * @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 |

TSDoc

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

To enable, add:

{
  "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:

   yarn install

4. Make changes and make sure that tests pass:

   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.