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.