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.