|
1 |
| -jsdoc.vim |
2 |
| -========= |
| 1 | +# jsdoc.vim |
3 | 2 |
|
4 | 3 | [](https://travis-ci.org/heavenshell/vim-jsdoc)
|
5 | 4 |
|
6 | 5 | jsdoc.vim generates [JSDoc](http://usejsdoc.org/) block comments based on a function signature.
|
7 | 6 |
|
8 |
| - |
| 7 | + |
9 | 8 |
|
10 |
| -This plugin based on https://gist.github.com/3903772#file-jsdoc-vim written by [NAKAMURA, Hisashi](https://gist.github.com/sunvisor) |
| 9 | +## Note |
11 | 10 |
|
12 |
| -Depending on your configuration, jsdoc.vim will prompt for description, `@return` type and description. It will also prompt you for types and descriptions for each function `@param`. |
| 11 | +Since version 2.0.0 jsdoc.vim is support only **Vim8**. |
13 | 12 |
|
14 |
| -Data type tab completion supported for parameter and return types |
15 |
| -* currently: `boolean`, `null`, `undefined`, `number`, `string`, `symbol`, `object`, `function`, `array`, `typedArray`, `date`, `promise`, `proxy`, `map`, `set`, `weakmap`, `weakset`, `error`, `regexp` |
| 13 | +If you want use old version checkout [1.0.0](https://github.com/heavenshell/vim-jsdoc/releases/tag/1.0.0>). |
| 14 | + |
| 15 | +## Install |
| 16 | + |
| 17 | +Since version 2.0.0, jsdoc.vim requires [lehre](https://www.npmjs.com/package/lehre). |
| 18 | + |
| 19 | +You can install following command. |
| 20 | + |
| 21 | +```console |
| 22 | +make install |
| 23 | +``` |
| 24 | + |
| 25 | +If you want to update `lehre` hit following commands. |
| 26 | + |
| 27 | +```console |
| 28 | +make clean |
| 29 | +make Install |
| 30 | +``` |
| 31 | + |
| 32 | +If you want install lehre manually, you can install from npm. |
| 33 | + |
| 34 | +```console |
| 35 | +$ yarn add -D lehre |
| 36 | +``` |
| 37 | + |
| 38 | +Than set installed `/path/to/node_modules/.bin/lehre` path to `g:jsdoc_lehre_path`. |
16 | 39 |
|
17 | 40 | ## Usage
|
18 | 41 |
|
19 |
| - 1. Move cursor on `function` keyword line. |
20 |
| - 2. Type `:JsDoc` to insert JSDoc. |
21 |
| - 3. Insert JSDoc above the `function` keyword line. |
| 42 | +1. Move cursor on `function` keyword line |
| 43 | +1. Type `:JsDoc` to insert JSDoc |
| 44 | +1. Insert JSDoc above the `function` keyword line |
| 45 | + |
| 46 | +## Format |
| 47 | + |
| 48 | +1. Type `:JsDocFormat` |
| 49 | +1. Insert JSDoc above the all signatures |
22 | 50 |
|
23 | 51 | ## Configuration
|
24 | 52 |
|
25 |
| -Option | Default | Description |
26 |
| -:-------------------------------------- | :------ | :---------- |
27 |
| -**g:jsdoc_allow_input_prompt** | 0 | Allow prompt for interactive input. |
28 |
| -**g:jsdoc_input_description** | 0 | Prompt for a function description |
29 |
| -**g:jsdoc_additional_descriptions** | 0 | Prompt for a value for `@name`, add it to the JSDoc block comment along with the `@function` tag. |
30 |
| -**g:jsdoc_return** | 1 | Add the `@return` tag. |
31 |
| -**g:jsdoc_return_type** | 1 | Prompt for and add a type for the aforementioned `@return` tag. |
32 |
| -**g:jsdoc_return_description** | 1 | Prompt for and add a description for the `@return` tag. |
33 |
| -**g:jsdoc_access_descriptions** | 0 | Set value to 1 to turn on access tags like `@access <private\|public>`. Set value to 2 to turn on access tags like `@<private\|public>` |
34 |
| -**g:jsdoc_underscore_private** | 0 | Set value to 1 to turn on detecting underscore starting functions as private convention |
35 |
| -**g:jsdoc_allow_shorthand** | 0 | Set value to 1 to allow ECMAScript6 shorthand syntax. Since ver `0.5.0` deprecated. Use `g:jsdoc_enable_es6` instead. |
36 |
| -**g:jsdoc_param_description_separator** | ' ' | Characters used to separate `@param` name and description. |
37 |
| -**g:jsdoc_custom_args_hook** | {} | Override default type and description. See help more detail. |
38 |
| -**g:jsdoc_custom_args_regex_only** | 0 | When using `custom_args_hook`, only match against regexes |
39 |
| -**g:jsdoc_type_hook** | {} | Allow to insert default description depending on the type. |
40 |
| -**g:jsdoc_enable_es6** | 0 | Enable to use ECMAScript6's Shorthand function, Arrow function. |
41 |
| -**g:jsdoc_tags** | see :h | Allow use of alternate tags (the ones that support synonyms) per JSDoc documentation. Can be changed on a per tag basis, for example: `let g:jsdoc_tags = {} \| let g:jsdoc_tags['param'] = 'arg'` |
42 |
| -**g:jsdoc_user_defined_tags** | {} | Allow use of `user_defined_tags`. |
| 53 | +Option |Default |Description |
| 54 | +:--------------------------|:-------------|:----------------------- |
| 55 | +**g:jsdoc_templates_path** |'' |Path to custom template. |
| 56 | +**g:jsdoc_formatter** |'jsdoc' |Document block formatter, `jsdoc`, `esdoc`, `tsdoc` |
| 57 | +**g:jsdoc_lehre_path** |'./lib/lehre' |Path to [`lehre`](https://www.npmjs.com/package/lehre). |
| 58 | + |
| 59 | +## Formatter |
| 60 | + |
| 61 | +You can choose formatter from [JsDoc](https://jsdoc.app/), [ESDoc](https://esdoc.org/), [TSDoc](https://github.com/microsoft/tsdoc). |
| 62 | + |
| 63 | +If you want to create your own template, see [example template](https://github.com/heavenshell/ts-lehre/tree/master/examples). |
| 64 | + |
| 65 | +## Intaractive input |
| 66 | + |
| 67 | +Since ver 2.0.0 input `Allow prompt for interactive input` is deprecated. |
| 68 | + |
| 69 | +If you want input Intaractively, use snippet plugin. |
| 70 | + |
| 71 | +See [snippet example template](./examples/snippet_template.js). |
43 | 72 |
|
44 | 73 | ## Keymap
|
45 |
| -Since version `0.3`, `g:jsdoc_default_mapping` was removed. |
46 | 74 |
|
47 |
| -Add following setting to .vimrc if you want same behavior as version `0.2.1`. |
48 |
| -```viml |
| 75 | +You can add following setting to .vimrc |
| 76 | +```vim |
49 | 77 | nmap <silent> <C-l> <Plug>(jsdoc)
|
50 | 78 | ```
|
51 | 79 |
|
52 | 80 | Alternatively, you could add the following setting to your .vimrc to search for the last `function` declaration
|
53 | 81 | and puts your jsdoc above it:
|
54 |
| -```viml |
| 82 | +```vim |
55 | 83 | nmap <silent> <C-l> ?function<cr>:noh<cr><Plug>(jsdoc)
|
56 | 84 | ```
|
57 | 85 |
|
58 |
| -## TypeScript |
59 |
| -Since ver 0.10.0 jsdoc.vim support TypeScript. |
| 86 | +## Thanks |
| 87 | +- This plugin based on https://gist.github.com/3903772#file-jsdoc-vim written by [NAKAMURA, Hisashi](https://gist.github.com/sunvisor) |
60 | 88 |
|
61 |
| -```typescript |
62 |
| -function foo(foo: string): string { |
63 |
| - return 'foo' |
64 |
| -} |
65 |
| -``` |
| 89 | +- The idea of npm packages installation is from [vim-lsp-settings](https://github.com/mattn/vim-lsp-settings). |
| 90 | +Highly applicate [@mattn](https://github.com/mattn/) and all vim-lsp-settings contributors. |
66 | 91 |
|
67 |
| -`:JsDoc` would generate following. |
68 |
| - |
69 |
| -```typescript |
70 |
| -/** |
71 |
| - * foo |
72 |
| - * |
73 |
| - * @param {string} foo |
74 |
| - * @returns {string} |
75 |
| - */ |
76 |
| -function foo(foo: string): string { |
77 |
| - return 'foo' |
78 |
| -} |
79 |
| -``` |
80 |
| -`param` and `returns` set `type` automatically. |
| 92 | +## LICENSE |
| 93 | +New BSD LICENSE |
0 commit comments