1 | [![NPM](https://nodei.co/npm/prettier-plugin-jsdoc.png)](https://nodei.co/npm/prettier-plugin-jsdoc/)
|
2 |
|
3 | [![install size](https://packagephobia.now.sh/badge?p=prettier-plugin-jsdoc)](https://packagephobia.now.sh/result?p=prettier-plugin-jsdoc)
|
4 | [![dependencies](https://david-dm.org/hosseinmd/prettier-plugin-jsdoc.svg)](https://david-dm.org/hosseinmd/prettier-plugin-jsdoc.svg)
|
5 |
|
6 | ![Prettier Banner](https://raw.githubusercontent.com/prettier/prettier-logo/master/images/prettier-banner-light.png)
|
7 |
|
8 | # prettier-plugin-jsdoc
|
9 |
|
10 | Prettier plugin for format comment blocks and convert to standard
|
11 | Match with Visual studio and other IDE which support jsdoc and comments as markdown.
|
12 |
|
13 | Many good examples of how this plugin work, are in tests directory.
|
14 | Compare tests and their snapshot
|
15 |
|
16 | Configured with best practices of jsDoc style guides.
|
17 |
|
18 | ## TOC
|
19 |
|
20 | - [Installation](#Installation)
|
21 | - [Examples](#Examples)
|
22 | - [Links](#Links)
|
23 | - [Options](#Options)
|
24 | - [Support](#Support)
|
25 |
|
26 | ## Installation
|
27 |
|
28 | 1. Install and configure Prettier as usual
|
29 | 2. Install prettier-plugin-jsdoc
|
30 |
|
31 | ```npm
|
32 | npm i prettier-plugin-jsdoc --save
|
33 | ```
|
34 |
|
35 | ```yarn
|
36 | yarn add prettier-plugin-jsdoc
|
37 | ```
|
38 |
|
39 | ## Config
|
40 |
|
41 | Set `prettier-plugin-jsdoc` to your plugins list.
|
42 |
|
43 | .prettierrc
|
44 |
|
45 | ```json
|
46 | {
|
47 | "plugins": ["prettier-plugin-jsdoc"],
|
48 | };
|
49 | ```
|
50 |
|
51 | If you want ignore some type of files remove "prettier-plugin-jsdoc" from plugins or add empty plugins
|
52 |
|
53 | ```.prettierrc.js
|
54 | module.exports = {
|
55 | "plugins": ["prettier-plugin-jsdoc"]
|
56 | overrides: [
|
57 | {
|
58 | files: '*.tsx',
|
59 | options: {
|
60 | "plugins": []
|
61 | },
|
62 | },
|
63 | ],
|
64 | };
|
65 | ```
|
66 |
|
67 | ## Ignore
|
68 |
|
69 | To ignore prettier use `/* */` or `//` instead of /\*\* \*/
|
70 |
|
71 | ## Examples
|
72 |
|
73 | #### Single line
|
74 |
|
75 | ```js
|
76 | /**
|
77 | * @param { string } param0 description
|
78 | */
|
79 | function fun(param0) {}
|
80 | ```
|
81 |
|
82 | Format to
|
83 |
|
84 | ```js
|
85 | /** @param {string} param0 Description */
|
86 | function fun(param0) {}
|
87 | ```
|
88 |
|
89 | #### React Component
|
90 |
|
91 | ```js
|
92 | /**
|
93 | * @type {React.FC<{ message:string} >}
|
94 | */
|
95 | const Component = memo(({ message }) => {
|
96 | return <p>{message}</p>;
|
97 | });
|
98 | ```
|
99 |
|
100 | Format to
|
101 |
|
102 | ```js
|
103 | /** @type {React.FC<{message: string}>} */
|
104 | const Component = memo(({ message }) => {
|
105 | return <p>{message}</p>;
|
106 | });
|
107 | ```
|
108 |
|
109 | #### Typescript Objects
|
110 |
|
111 | ```js
|
112 | /**
|
113 | @typedef {
|
114 | {
|
115 | "userId": {
|
116 | "profileImageLink": *,
|
117 | "isBusinessUser": "isResellerUser"|"isBoolean"| "isSubUser" | "isNot",
|
118 | "shareCode": number,
|
119 | "referredBy": any,
|
120 | },
|
121 | id:number
|
122 | }
|
123 | } User
|
124 | */
|
125 | ```
|
126 |
|
127 | Format to
|
128 |
|
129 | ```js
|
130 | /**
|
131 | * @typedef {{
|
132 | * userId: {
|
133 | * profileImageLink: any;
|
134 | * isBusinessUser: "isResellerUser" | "isBoolean" | "isSubUser" | "isNot";
|
135 | * shareCode: number;
|
136 | * referredBy: any;
|
137 | * };
|
138 | * id: number;
|
139 | * }} User
|
140 | */
|
141 | ```
|
142 |
|
143 | #### Example
|
144 |
|
145 | Add code to example tag
|
146 |
|
147 | ```js
|
148 | /**
|
149 | * @examples
|
150 | * var one= 5
|
151 | * var two=10
|
152 | *
|
153 | * if(one > 2) { two += one }
|
154 | */
|
155 | ```
|
156 |
|
157 | to
|
158 |
|
159 | ```js
|
160 | /**
|
161 | * @example
|
162 | * var one = 5;
|
163 | * var two = 10;
|
164 | *
|
165 | * if (one > 2) {
|
166 | * two += one;
|
167 | * }
|
168 | */
|
169 | ```
|
170 |
|
171 | #### Description
|
172 |
|
173 | Description is formatting as Markdown, so you could use any features of Markdown on that. Like code tags ("```js"), header tags like "# AHeader" or other markdown features.
|
174 |
|
175 | ## Options
|
176 |
|
177 | | Key | type | Default | description |
|
178 | | :-------------------------------- | :------ | :-------- | ----------------------------------------------------------------------------------------- |
|
179 | | jsdocSpaces | Number | 1 |
|
180 | | jsdocDescriptionWithDot | Boolean | false |
|
181 | | jsdocDescriptionTag | Boolean | false |
|
182 | | jsdocVerticalAlignment | Boolean | false |
|
183 | | jsdocKeepUnParseAbleExampleIndent | Boolean | false |
|
184 | | jsdocSingleLineComment | Boolean | true |
|
185 | | jsdocCapitalizeDescription | Boolean | true |
|
186 | | jsdocSeparateReturnsFromParam | Boolean | false | Add an space between last @param and @returns |
|
187 | | jsdocSeparateTagGroups | Boolean | false | Add an space between tag groups |
|
188 | | jsdocPreferCodeFences | Boolean | false | Always fence code blocks (surround them by triple backticks) |
|
189 | | tsdoc | Boolean | false |
|
190 | | jsdocPrintWidth | Number | undefined | If You don't set value to jsdocPrintWidth, the printWidth will be use as jsdocPrintWidth. |
|
191 |
|
192 | Full up to date list and description of options can be found in Prettier help. First install plugin then run Prettier with "--help" option.
|
193 |
|
194 | `$ prettier --help` # global installation
|
195 |
|
196 | `$ ./node_modules/.bin/prettier --help` # local installation
|
197 |
|
198 | ## ESLint
|
199 |
|
200 | Install [eslint-plugin-prettier](https://github.com/prettier/eslint-plugin-prettier)
|
201 |
|
202 | ```
|
203 | $ yarn add eslint eslint-plugin-prettier
|
204 | ```
|
205 |
|
206 | Then, in your .eslintrc.json:
|
207 |
|
208 | ```json
|
209 | {
|
210 | "plugins": ["prettier"],
|
211 | "rules": {
|
212 | "prettier/prettier": "error"
|
213 | }
|
214 | }
|
215 | ```
|
216 |
|
217 | ## Tsdoc
|
218 |
|
219 | We hope to support whole tsdoc, if we missed somethings please create an issue.
|
220 |
|
221 | ```json
|
222 | {
|
223 | "tsdoc": true
|
224 | };
|
225 | ```
|
226 |
|
227 | ## Contribute
|
228 |
|
229 | 1- Get a clone/fork of repo
|
230 |
|
231 | 2- Install yarn
|
232 |
|
233 | 3- Add your changes
|
234 |
|
235 | 4- Add a test to your change if needed
|
236 |
|
237 | 5- Create PR
|
238 |
|
239 | This project extended from @gum3n worked project on GitLab.
|
240 |
|
241 | ## Links
|
242 |
|
243 | [Prettier](https://prettier.io)
|
244 |
|
245 | [JSDoc](https://jsdoc.app)
|
246 |
|
247 | ## Support
|
248 |
|
249 | [![Donate with Bitcoin](https://en.cryptobadges.io/badge/big/3APtLaZxL9Dk4enQmSY4qWBo5TctWuvW5T)](https://en.cryptobadges.io/donate/3APtLaZxL9Dk4enQmSY4qWBo5TctWuvW5T)
|
250 |
|
251 | [![Donate with Ethereum](https://en.cryptobadges.io/badge/big/0x90a68640d77c8a03d1a5b55f49a5175c756cc3a3)](https://en.cryptobadges.io/donate/0x90a68640d77c8a03d1a5b55f49a5175c756cc3a3)
|