Best practices and tools for documenting vimscript functions?

Question

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>
endfunction

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

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
endfunction   

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

"===  FUNCTION  ================================================================
"          NAME:  compare
"   DESCRIPTION:  <+DESC+>
"    PARAMETERS:  thee - <+DESCRIPTION+>
"                 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 )
else
  <+ELSE_PART+>
endif

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.