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.

.prettierrc:

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

TSDoc

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

To enable, add:

{
  "tsdoc": true
}

Supported Prettier versions

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.