hosseinmd
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
npm install prettier-plugin-jsdoc --save-devyarn add prettier-plugin-jsdoc --devConfiguration
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
| 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) |
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 |
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
- Fork and clone the repository
- Install Yarn
Install project dependencies:
yarn install- Make changes and make sure that tests pass:
yarn run test - Update or add tests to your changes if needed
- Create PR
Links
Acknowledge
This project extended from the @gum3n worked project on GitLab.