I have quickly skimmed through :h user-functions and a couple random vim plugins and all I could find were patterns like

" one-line short function description
function foo()
  <function body here>

but I'm not happy with this.

Are there any tools / vim plugins that offer the following features:

  1. a standard syntax that allows verbose documentation of functions, including info about arguments, their type, their meaning, as well as returned values of functions

  2. can process vim scripts looking for said docs and generate vim help files

I am looking for something similar to sphinx of python and jsdoc of javascript, but for vim code


1 Answer 1


I've never encountered anything that matches both of the specific specs you mention but I know of a Vim plugin that offers some of what you mention in the first item, i.e. documentation assistance. For instance, you can easily insert a template-based, verbose function doc/comment.

Given this Vim function:

function! compare ( thee, summers_day )
    " something

You can put the cursor on the first line and hit \ca and this will be generated:

"===  FUNCTION  ================================================================
"          NAME:  compare
"                 summers_day - <+DESCRIPTION+>
"       RETURNS:  

I think the cursor is put on the first "form field" and you can hit Ctrl+J to move to subsequent fields.

The plugin is called Vim Support and, FYI, they have similar Vim plugins that support other languages such as Bash, Perl and C/C++. They are linked to that same page.

There are a number of other key mappings that will insert file header, date-times, if/else/elseif, try/catch, for, etc. outlines, iterator templates, and so on.

One more example...given

let x = sqrt ( y )

Select this with Visual mode and hit \sie and you'll get...

if |
  let x = sqrt ( y )

The tag in the else block can be jumped and overwritten with your code.

You can also create custom "snippets"; personal templates that include anything you can think of. They're tied to a key mapping + menu selection.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.