heavenshell/vim-jsdoc

Generate JSDoc to your JavaScript code.

jsdoc.vim

jsdoc.vim generates JSDoc block comments based on a function signature.

Note

jsdoc.vim supports Vim8.

Neovim works since v2.1.0, but if something wrong, send me pull requests to fix it.

If you want use old version checkout 1.0.0.

Requirements

Node v12.x or above.

Install

Vim Plug

Plug 'heavenshell/vim-jsdoc', {
  \ 'for': ['javascript', 'javascript.jsx','typescript'],
  \ 'do': 'make install'
\}

PlugUpdate error

If you got `yarn.lock` related error,

error: Your local changes to the following files would be overwritten by merge:
    lib/yarn.lock

Run following command

cd /path/to/plugged/vim-jsdoc
git checkout -- yarn.lock

and re-run PlugUpdate

Manual Installation

Since version 2.0.0, jsdoc.vim requires a local copy lehre installed to the plugin directory.

You can install lehre with:

# cd to <vim-jsdoc path>
make install

If you want to update lehre use:

make clean
make install

If you want to install lehre manually, you can install from npm.

$ yarn add -D lehre

Set installed /path/to/node_modules/.bin/lehre path to g:jsdoc_lehre_path.

Installing on Windows

# cd to <vim-jsdoc path>/lib
npm install

If you want to set the path of lehre manually on Windows, you should use the path with the file extension .cmd, such as /path/to/node_modules/.bin/lehre.cmd.

Usage

1. Move cursor on function keyword line
2. Type :JsDoc to insert JSDoc
3. Insert JSDoc above the function keyword line

Format

1. Type :JsDocFormat
2. Insert JSDoc above the all signatures

Configuration

Option	Default	Description
g:jsdoc_templates_path	''	Path to custom template.
g:jsdoc_formatter	'jsdoc'	Document block formatter, jsdoc, esdoc, tsdoc
g:jsdoc_lehre_path	'./lib/lehre'	Path to lehre.

Formatter

You can choose formatter from JsDoc, ESDoc, TSDoc.

If you want to create your own template, see example template.

Interactive input

Since ver 2.0.0 input Allow prompt for interactive input is deprecated.

If you want input Interactively, use snippet plugin.

See snippet example template.

Keymap

You can add following setting to .vimrc

nmap <silent> <C-l> <Plug>(jsdoc)

Alternatively, you could add the following setting to your .vimrc to search for the last function declaration and puts your jsdoc above it:

nmap <silent> <C-l> ?function<cr>:noh<cr><Plug>(jsdoc)

Thanks

• This plugin based on https://gist.github.com/3903772#file-jsdoc-vim written by NAKAMURA, Hisashi

• The idea of npm packages installation is from vim-lsp-settings. Highly applicate @mattn and all vim-lsp-settings contributors.

LICENSE

New BSD LICENSE

vim-jsdoc's Issues

Same description is provided for all parameters

I just pressed Enter. Probably a side-effect of #26.

/**
 * bar
 *
 * @name bar
 * @function
 * @param a {Function} The callback function.
 * @param b {Function} The callback function.
 * @param c {Function} The callback function.
 */
function bar(a, b, c) {
    return a + b + c;
}

Autoformatting support

Would love for an option to allow automatic formatting. Currently going in by hand afterwards to make alignments

Param defaults as optional?

Using the ES6 code for handling defaults and :JsDoc with prompts enabled it generates the following

  /**
   * getChildren
   *
   * @param {int} id
   * @param {int} pageSize=10
   * @param {int} page=1
   * @returns {Promise}
   */
  getChildren(id, pageSize = 10, page = 1) {

However as per the JSDoc documentation, should those params with defaults be listed as optional? ie

  /**
   * getChildren
   *
   * @param {int} id
   * @param {int} [pageSize=10]
   * @param {int} [page=1]
   * @returns {Promise}
   */
  getChildren(id, pageSize = 10, page = 1) {

Errors when using plugin with input prompt disabled

Thanks for the plugin, it is just what I'm looking for! That being said, out of the box I'm getting an error when I try to execute :JsDoc with let g:jsdoc_allow_input_prompt=0 and I'm not sure how to go about debugging it.

~/workspace/D16GRodeoWebsite/src/AdvertisingReactComponents/src/advertiser/model.js" 115L, 3169C
Error detected while processing function jsdoc#insert..<SNR>113_hookArgs:
line   28:
E171: Missing :endif
Error detected while processing function jsdoc#insert:
line   95:
E706: Variable type mismatch for: l:lines
Error detected while processing function jsdoc#insert..<SNR>113_hookArgs:
line   28:
E171: Missing :endif
Error detected while processing function jsdoc#insert:
line   95:
E706: Variable type mismatch for: l:lines

It seems to work fine with let g:jsdoc_allow_input_prompt=1 though.

Error thrown for some functions

The following is thrown for some function definitions in classes. It seems pretty random and does it for really simple function, even empty ones with no parameters sometimes. It's a React project so these are methods on classes.

I can't seem to see a pattern so hoping this will mean something to somebody.

Error detected while processing function jsdoc#insert[135]..<SNR>102_hookArgs:
line    4:
E716: Key not present in Dictionary: param
E116: Invalid arguments for function printf(' * @%s %s', g:jsdoc_tags['param'], a:arg)
E15: Invalid expression: printf(' * @%s %s', g:jsdoc_tags['param'], a:arg)
Press ENTER or type command to continue

Support ES6 class methods

class Parser {

    constructor (app) {
       ...
    }

    // This should be able to generate a nice comment
    parse (cb) {
      ...
    }
}

Is this a known issue or it's something that needs to be improved?

ES6 jsdoc generation

in ES6 classes like

class Foo {
  constructor(greeting) {
    this.greeting = greeting;
  }

  hello(name) {
    return this.greeting + ", " + name;
  }
}

it won't realize the return value nor the params

Support for ES6 syntax class methods

Running :JsDoc on the following

function thisWorks(a, b, c) {}

class SimpleClass {
  thisDoesNotWork(a, b, c) {}
}

Generates

/**
 * thisWorks
 *
 * @param a
 * @param b
 * @param c
 * @returns {undefined}
 */
function thisWorks(a, b, c) {}

class SimpleClass {
  /**
   * 
   *
   * @returns {undefined}
   */
  thisDoesNotWork(a, b, c) {}
}

Arrow Functions Not Supported

When attempting to document arrow functions I ran into this issue.

When I run :JsDoc on the following methods, the displayed JsDoc is generated.

/**
 *
 *
 * @return {undefined}
 */
const f = (arg1, arg2) => true;
/**
 * f
 *
 * @param arg1
 * @param arg2
 * @return {undefined}
 */
const f = function(arg1, arg2) {
    return true;
};

The arrow functions do not generate parameters or method names.

Missing @param around single function argument on ES6 shorthand function

With parens around single argument:

/**
 * updateVPNStatus
 *
 * @param newStatus
 * @returns {undefined}
 */
const updateVPNStatus = (newStatus) => ...

Without:

/**
 * 
 *
 * @returns {undefined}
 */
const updateVPNStatus = newStatus => ...

Default descriptions checking the argument name

Is it possible to have a way to create default descriptions?

e.g. if (field === "callback") { defaultDesc = "The callback function"; }

And also, the type: Function.

This would be awesome! Thanks for great plugin. 🍀

E492: Not an editor command: JsDoc

Sorry to ask such a question here, because this is not your bug for certain.
But I googled a lot of time, no solution found. So I have to seek for help here.

I use Vim 8.0.707 in Debian 9, and I clone this git repository into this path:
~/.vim/pack/plugins/start/vim-jsdoc
Then I open my js file, type :JsDoc, and see this error: E492: Not an editor command: JsDoc
But if I type :call jsdoc#insert(), it will add some docs to my function without prompts like the gif in the README.md

So how to setup my vim to enable :JsDoc and make it running like your gif?

Support static function

#44 (comment)

windows offer

can offer the windows neovim or gvim version

g:jsdoc_input_description duplicated in help

g:jsdoc_input_description duplicated in help.

Default message depending on the type

Is it possible to add a way to define default descriptions depending on the type? Like, #24, but after providing the type I want to just press Enter and create the description automagically.

For example: Object, then I press twice Enter and I want to get @param {Object} arg An object containing the following fields: (which is supposed to be configured somewhere in .vimrc).

Btw, do you have a PayPal account? I'm happy to donate you some 💲 for making my life easier using this plugin. 😄

how to make :JsDoc append @author or @date automatically?

how to make :JsDoc append @author or @Date automatically?

How to use it in vue?

I'm currently using vue, how can I use this plugin in vue?

g:jsdoc_access_descriptions Behavior Reversed

Reading through the README, my impression is that if g:jsdoc_access_descriptions is set to 2, the resulting documentation for a private method would be @private or @public. However, on line 122, the code uses @access public and @access private.

Testing this in my .vimrc file I can confirm that behavior.

Is this an indication that the documentation, or implementation, is incorrect?

Typescript support

It'd be nice if the plugin had typescript support (automatically detect types for parameter and return value, if specified).

Generated comment block doesn't follow whitespace settings (tabs vs. spaces)

The comment block generated by this plugin will be indented with spaces rather than tabs even when Vim is configured to use tabs and the file is tab-indented.

Hook arg matchstr is incorrectly reversed

See

vim-jsdoc/autoload/jsdoc.vim

Line 149 in d5dfde1

let l:matchedArg = matchstr(a:hook, a:arg)

function! s:hookArgs(lines, space, arg, hook, argType, argDescription)
  " Hook function signature's args for insert as default value.
  if g:jsdoc_custom_args_hook == {}
    call add(a:lines, a:space . ' * @' . g:jsdoc_tags['param'] . ' ' . a:arg)
  else
    let l:matchedArg = matchstr(a:hook, a:arg)

The call to matchstr is called with the first arg being the hook, the second arg as the function parameter

so for the javascript

function myf(isBoolean) {
}

it is run against:

matchstr(regexPattern, 'isBoolean')

According to the vim docs, matchstr should be called:

match("testing", "ing")

That is, match('isBoolean', regexPattern)

@return if function returns undefined

Plugin adds empty @return param, if I don't specify the type of returned value. Like this:

/**
 * log
 *
 * @param {string} value
 * @return
 */
 function log(value) {
    console.log(value);
 }

(implemented here: https://github.com/heavenshell/vim-jsdoc/blob/master/autoload/jsdoc.vim#L96)

Isn't it better to specify the type explicitly by default. Like:

* @return {undefined}

Optional binding to something other than <C-l>

I use <C-h/j/k/l> to switch between buffers. vim-jsdoc overwrites that mapping for <C-l>. It'd be nice to have this as a plugin option. I'm a vimscript newbie or else I'd do it myself. Any idea how to fix this?

Autodetect params type

There is code-analysis engine for JavaScript named Tern which actually analyses js code very well. One of the feature - it can automatically, based on the code, determine the type of variable/parameter. You can try it out online on this demo page. Also, there is vim plugin for this.

So, my question is: is there any chase vim-jsdoc plugin could be integrated with the Tern engine to automatically generate/suggest types for @parameters/@return statements?

TypeScript inputs configuration

Hi,
I'm trying to configure the plugin to automatically get the input types from the typescript declaration but to have it asking me the description of each param.

Sadly if I set

let g:jsdoc_allow_input_prompt = 0
let g:jsdoc_input_description = 1

the plugin doesn't ask for the description but if I try

let g:jsdoc_allow_input_prompt = 1
let g:jsdoc_input_description = 1

then it ignores the types specified in the function.

Am I missing something?

Does vim-jsodc support @typedef ?

How to generator such JSDoc ?

/**
 * @typedef Point
 * @type Object
 * @property {number} x The X Coordinate
 * @property {number} y The Y Coordinate
 */

/**
 * Returns a coordinate from a given mouse or touch event
 * @param  {TouchEvent|MouseEvent|jQuery.Event} e    
 *         A valid mouse or touch event or a jQuery event wrapping such an
 *         event. 
 * @param  {string} [type="page"]
 *         A string representing the type of location that should be
 *         returned. Can be either "page", "client" or "screen".
 * @return {Point} 
 *         The location of the event
 */
var getEventLocation = function(e, type) {
    ...

    return {x: xLocation, y: yLocation};
}

poor choice of default keybind

<C-l> is used for redrawing the screen, overriding this as a default is a very poor choice IMO.

I'd like to suggest <leader>jd, or (my personal favorite) not defining any keybinds and let the user do it manually.

ECMAScript6 method shorthand support

Doesn't work with new style method definitions. Here is an example -- given these functions, I typed :JsDoc and got the annotations as noted:

Old style:

  /**
   * updateData
   *
   * @param data
   * @return {undefined}
   */
  updateData: function(data) {
    this.data = data;
    this.trigger(data);
  },

New style (shorthand):

  /**
   * 
   *
   * @return {undefined}
   */
  updateData(data) {
    this.data = data;
    this.trigger(data);
  },

ES6 Destructured Object Function Argument

Hi,

Right now destructured function parameters are broken:

const obj = {
  a: 'a',
  b: 'b',
  other: '...',
}

/**
 * DocBlock
 *
 * @param {} {a
 * @param {} b}
 */
function objectAB ({ a, b }) {
  return a + b
}

objectAB(obj)

Of course this is a matter of opinion, but I think the spread object argument should be one parameter like

/**
 * DocBlock
 *
 * @param {obj} { a, b } Param Comment
 */

nullable @member syntax issue

This highlights fine:

/** @type {?Object} */

---

This doe NOT highlight fine:

/** @member {?Object} */

Fix README.md

jsdoc_input_description default value

I have a little question.

Its source code,

if !exists('g:jsdoc_input_description')
  let g:jsdoc_input_description = 0
endif

but, README file(or doc file) says g:jsdoc_input_description is default value is 1.

which is correct??

ES6 class support

ES6 is now very popular and I think it is reasonable to support both function and class class definition. Is it in the plan? If not, I could investigate how to implement this. :)

Option to omit @return if no type given

I find it redundant to include the @return {undefined} for the many functions I have which do not have a return type. Can this be implemented?

Unable to generate @public or @private

I haven't been able to get @public or @private options generated using the following config:

let g:jsdoc_allow_input_prompt = 1
let g:jsdoc_input_description = 1
let g:jsdoc_access_descriptions = 2
let g:jsdoc_underscore_private = 1
let g:jsdoc_enable_es6 = 1

Is there supposed to be an additional prompt when using the :JsDoc command?

Sometimes the jsdoc comment is not generated properly

Here is a case when the comment is incorrect:

/**
 * ParentSearch
 *
 * @name ParentSearch
 * @function
 * @param path
 * @param search
 * @param options
 * @param callback {d} asd
 * @param progress {Function} The progress function.
 */
function ParentSearch(path, search, options, callback, progress) {
   // ...
}

I provided information about path, search, options and callback as well. The progress data is completed from defaults.

The first arguments descriptions and types are missing.

What is the test framework?

Hello,

Sorry if this is a dumb question ... I'm doing some private extensions of vim-jsdoc to support our company's private extensions of JsDoc. I would like to develop tests for what I'm doing. I see that there are example .js files in the test/ directory, but I don't see any script to automate testing against those. What test framework are you using? How can I run these tests?

Thanks,
-mykle-

Unknown function: job_start

I've updated to 2.0 and am getting this error when running :JsDoc:

Error detected while processing function jsdoc#insert[28]..275:
line    5:
E117: Unknown function: job_start
E15: Invalid expression: job_start(a:cmd, { 'callback': {_, m -> a:cb(m, a:start_lineno, a:is_method)}, 'exit_cb': {_, m -> a:ex_cb(m)}, 'in_mode': 'nl', })
line   11:
E121: Undefined variable: s:job
E116: Invalid arguments for function job_getchannel
E15: Invalid expression: job_getchannel(s:job)
line   12:
E121: Undefined variable: channel
E116: Invalid arguments for function ch_status
E15: Invalid expression: ch_status(channel) ==# 'open'

I installed lehre globally with yarn global add lehre, and added this to my .vimrc:

let g:jsdoc_lehre_path = '/usr/local/bin/lehre'

where /usr/local/bin/lehre is what is returned when I run which lehre in the command line.

Anything I can do here? Is this a problem with a global install of lehre?

Multiline function definitions don't work

The following doesn't seem to work with vim-jsdoc:

function(a, b, c
              d, e, f) {
}

Detect generator functions

When trying to JsDoc generator functions, the params and function name are not detected.

e.g.

JobLogic.prototype.assignJobsScr = function *(x, y) {
    //...
};

No detection of parameters when function is a parameter by itself

for example:

process.on('uncaughtException', function (err) {
    console.error('Caught exception: ' + err);
    console.log('Exiting nicely...');
    process.exit(1);
});

Will generate a jsDoc of:

/**
 * 
 *
 * @return
 */

This happens whenever a function is a parameter by itself.

rethinking about this - maybe this is expected behavior but still leaving this open for thoughts

Tools used to create animated gif?

Nice plugin! Minor aside: Which tools did you use to create the animated gif screenshot with keypresses? Very cool.

Thanks!

After upgrade, it generates invalid jsdoc

I'm not sure what's going on:

/**
 * ParentSearch
 *
 * @name ParentSearch
 * @function
 * @param a {String} Foo
 */
function ParentSearch(a) {
}

I expect to get * @param {String} a Foo

jsdoc.vim v2.0.0

Hello, jsdoc.vim users.
I'm sorry for long time no update and response.

I'm currently working on jsdoc.vim v2.0.0

What's new

• Complete re-write
• Can handle complex params

For example.

const foo = (arg1: (arg1: { foo: string, bar: number }) => string, arg2: number) => {}

will generate like following.

/**
 * foo.
 *
 * @param {Function} arg1
 * @param {number} arg2
 */
const foo = (arg1: (arg1: { foo: string, bar: number }) => string, arg2: number) => {}

• You can choose document block template from JSDoc, ESDoc, TSDoc and your own customaized template

Deprecate

v2.0.0 will Deprecate all g:jsdoc_* variables.
interactive mode is also deprecate but you can use snippet plugin and custmaized template to insert document interactive.

Current version is too much global variables.
v2.x will be less global variables.

Support Vim version

First release of v2.0.0 will only support Vim8.
I know some of user use Neovim, but I don't have Neovim env and knowledges.
So after release v2.0.0, If you want to use in Neovim, please send me PR.

Release date

TBA. Hopefully I will release in near future.

Stay safe and take care.

Recent changes prevent Typescript support

Hi there! It seems some changes in via 45c7c7c now prevent typescript support.

When starting a sample js file, I can call :JsDoc
But when using typescript, I get E492: Not an editor command: JsDoc

minimal vim that produces it.

set runtimepath+=~/.config/nvim/repos/github.com/Shougo/dein.vim/
call dein#begin(expand('~/.config/nvim'))
call dein#add('Shougo/dein.vim')
call dein#add('HerringtonDarkholme/yats.vim', {'on_ft': ['typescript']})
call dein#add('heavenshell/vim-jsdoc')
if dein#check_install()
  call dein#install()
endif

call dein#end()
filetype plugin indent on
set clipboard+=unnamedplus

Return Type Includes Arrorw with Flow and Arrow Functions

Running :JsDoc on

const example = (key: string, val: string): string => {
  return val
}

produces the comment

/**
 * example
 *
 * @param {string} key
 * @param {string)} val
 * @returns {string =>}
 */

Enable parameters in shorthand methods with es6 feature

enable_es6 feature is not detecting parameters in shorthand class methods

In this method only it allows you to add a description and type to return value, not to parameter

class whatever {
  method (param) {
    // do something
  }
}

Can't get it to work with vim 7.4 + janus setup

I'm using pathogen via Janus and vim 7.4 - are there any known incompatibilities with other plugins?

I didn't see it in :scriptnames in cli vim and in MacVim I used the plugin listing plugin Headlights to show all my bundles and didn't see it there either.

Any ideas? Thanks!

ES6 Generator functions

Generating documentation for ES6 Generator functions doesn't work properly.

let generatorFn = function* (arg1, arg2) {};

Using JsDoc on the above function only adds description and return and doesn't recognize the arguments. This is most likely due to the function regex not considering '*' a valid character in between function and parenthesis.