You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+45-9Lines changed: 45 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,13 +10,49 @@ A [Prettier](https://prettier.io) plugin to format [JSDoc](https://jsdoc.app) bl
10
10
11
11
> If you are wondering why I built this, go to the [Motivation](#motivation) section.
12
12
13
+
- 📦 [Installation](#-Installation)
13
14
- ⚙️ [Options](#%EF%B8%8F-options)
14
15
- 🚫 [Ignoring blocks](#-ignoring-blocks)
15
16
- ⚡️ [Modifying the functionality](#%EF%B8%8F-modifying-the-functionality)
16
17
- 📖 [Troubleshooting](#-troubleshooting)
17
18
- 🤘 [Development](#-development)
18
19
- 🐞 [Validating bugs](#-validating-bugs)
19
20
21
+
### 📦 Installation
22
+
23
+
First, please check the [official documentation](https://prettier.io/docs/plugins#using-plugins) on how plugins are used.
24
+
25
+
Just to recap, and focusing in the configuration file approach, there are two ways in which you are probably going to be using this plugin:
26
+
27
+
#### 1. Adding it to your existing configuration
28
+
29
+
The simplest use case: you have a configuration with your rules, and you want to add the plugin. You'd need to define the `plugins` array, if you don't have it already, and add the plugin name to it:
30
+
31
+
```json
32
+
{
33
+
"tabWidth": 90,
34
+
"plugins": ["@homer0/prettier-plugin-jsdoc"]
35
+
}
36
+
```
37
+
38
+
#### 2. Extending an existing configuration and adding the plugin
39
+
40
+
This is kind of confusing in the official docs, because it's not linked in the "using plugins" section, but rather in the ["using a shareable config"](https://prettier.io/docs/sharing-configurations#using-a-shareable-config) section.
41
+
42
+
Unfortunately, Prettier doesn't have a way to use and extend an existing configuration with a JSON syntax, so you have to change to a JavaScript file:
43
+
44
+
```js
45
+
constconfig=require('@homer0/prettier-config');
46
+
47
+
module.exports= {
48
+
...config,
49
+
plugins: [
50
+
...(config.plugins|| []),
51
+
'@homer0/prettier-plugin-jsdoc'
52
+
],
53
+
};
54
+
```
55
+
20
56
### ⚙️ Options
21
57
22
58
-[`@description` tag](#description-tag)
@@ -29,7 +65,7 @@ A [Prettier](https://prettier.io) plugin to format [JSDoc](https://jsdoc.app) bl
29
65
-[Manage indentation for pseudo code examples](#manage-indentation-for-pseudo-code-examples)
30
66
-[`@access` tag](#access-tag)
31
67
-[Allow @access tag](#allow-access-tag)
32
-
-[Enfore the use of the @access tag](#enfore-the-use-of-the-access-tag)
68
+
-[Enforce the use of the @access tag](#enfore-the-use-of-the-access-tag)
33
69
-[Types with string literals](#types-with-string-literals)
34
70
-[Format types with string literals](#format-types-with-string-literals)
35
71
-[Specify quotes types for string literals](#specify-quotes-types-for-string-literals)
@@ -249,7 +285,7 @@ Whether or not the `@access` tag can be used; if `false`, when a tag is found, i
249
285
*/
250
286
```
251
287
252
-
##### Enfore the use of the @access tag
288
+
##### Enforce the use of the @access tag
253
289
254
290
| Option | Type | Default |
255
291
| ----------------------- | ------- | ------- |
@@ -529,9 +565,9 @@ Whether or not to sort the tags of a JSDoc block.
A list specifing the order in which the the tags of a JSDoc block should be sorted. It supports an `other` item to place tags that are not on the list.
570
+
A list specifying the order in which the the tags of a JSDoc block should be sorted. It supports an `other` item to place tags that are not on the list.
535
571
536
572
#### Rendering
537
573
@@ -608,7 +644,7 @@ The alternative:
608
644
| ------------------------ | ------- | ------- |
609
645
|`jsdocGroupColumnsByTag`| boolean |`true`|
610
646
611
-
Whether to respect column alignment within the same tag. For example: all `@param` tags are agligned with eachother, but not with all the `@throws` tags.
647
+
Whether to respect column alignment within the same tag. For example: all `@param` tags are aligned with each other, but not with all the `@throws` tags.
612
648
613
649
```js
614
650
// jsdocGroupColumnsByTag: false
@@ -642,7 +678,7 @@ Whether to respect column alignment within the same tag. For example: all `@para
642
678
| ------------------------ | ------- | ------- |
643
679
|`jsdocConsistentColumns`| boolean |`true`|
644
680
645
-
This is for when the columns are algined by tags; if `true` and one tag can't use columns, no other tag will use them either.
681
+
This is for when the columns are aligned by tags; if `true` and one tag can't use columns, no other tag will use them either.
646
682
647
683
```js
648
684
// jsdocConsistentColumns: true
@@ -997,7 +1033,7 @@ The problem is that the plugin will end up putting those lines together, as it w
997
1033
*/
998
1034
```
999
1035
1000
-
It may look like a bug, but this is actually the functionality that formats the the descriptions in order to respect the [`printWidth`/`jsodcPrintWidth`](#custom-width) option.
1036
+
It may look like a bug, but this is actually the functionality that formats the the descriptions in order to respect the [`printWidth`/`jsdocPrintWidth`](#custom-width) option.
1001
1037
1002
1038
The way you can solve this is by adding a period at the end of the line, which will tell the plugin that you ended the sentence and that it should respect the line break
- The `module.exports`specifiy the plugin options for that specific case.
1136
+
- The `module.exports`defines the plugin options for that specific case.
1101
1137
-`only: true` is not a plugin option, but will make the test runner ignore all the other tests, and only run the one you specify.
1102
1138
- Below `//# input` you can put any number of comment blocks, in the state you would expect the plugin to pick them.
1103
1139
- Below `//# output` you have to put the expected output after formatting the input with the plugin.
@@ -1113,4 +1149,4 @@ Ok, there won't accept options requests? that's perfect, it doesn't make sense t
1113
1149
1114
1150
Enough rant; I started using Prettier a couple of weeks ago and being a huge fan of JSDoc, I wanted to use it to format JSDoc blocks too, something I've doing, for sometime now, using a Node script that I was trying to make into a VSCode plugin :P.
1115
1151
1116
-
I found [prettier-plugin-jsdoc](https://github.com/hosseinmd/prettier-plugin-jsdoc/) by [@hosseinmd](https://github.com/hosseinmd), but it (currently) doesn't cover most of the cases I wanted (like columns creations), it's written in TypeScript (which I don't like very much) and if I were to fork and send PRs, it could've taken forever (you can see the commits for this package), and it seemed like the perfect oportunity to try [Ramda](https://ramdajs.com) and functional programming... so I started a new one.
1152
+
I found [prettier-plugin-jsdoc](https://github.com/hosseinmd/prettier-plugin-jsdoc/) by [@hosseinmd](https://github.com/hosseinmd), but it (currently) doesn't cover most of the cases I wanted (like columns creations), it's written in TypeScript (which I don't like very much) and if I were to fork and send PRs, it could've taken forever (you can see the commits for this package), and it seemed like the perfect opportunity to try [Ramda](https://ramdajs.com) and functional programming... so I started a new one.
0 commit comments