docgen.vim

Vim/neovim plugin for code documentation.

There is vim-doge already, how is this different?

Cons:

• less supported filetypes
• no javascript support
• no snippet-like placeholder switching

Pros:

• no external dependencies
• different commenting styles
• possible to update previous docstring
• command to create comment boxes, and to boxify current comments
• more flexible, and possibly easier to tweak/customize (if really needed)

Supported filetypes (as of now):

• c
• c#
• cpp
• java
• go
• lua
• python
• ruby
• bash
• vim
• gdscript
• vb (Visual Basic)

For some filetypes (especially c#, cpp and java) support may not be optimal, please open an issue if you find some problem.

Usage

Creating docstring is only possible in the supported filetypes, creating comment boxes should work with any filetype.

The commands are:

DocGen[!] [count]	create docstring
DocBox[!] [count]	create comment box, or boxify current comment

Or with mappings (example):

nmap ,d <Plug>(DocGen)
nmap ,D <Plug>(DocGen!)
nmap ,x <Plug>(DocBox)
nmap ,X <Plug>(DocBox!)

When you create a docstring, placeholders will be added, and the @/ register will be set to the placeholder. You can edit them with cgn, or use a more comfortable mapping, for example:

nnoremap <Space><Tab> cgn

Styles

The flexibility comes from the usage of bang and count in both mappings and commands.

docstring

There are 4 different styles for docstrings (using mappings from example):

style	mapping	effect
'default'	1,d	quite descriptive, using @brief tag
'boxed'	2,d	same but boxed
'simple'	3,d	similar but simpler
'minimal'	4,d	just the function name, no parameters

For c/cpp there are additional styles (kernel, kernelboxed, minimalboxed). In c/cpp there is also support for structs, unions, etc.

Also remember that using a count sets a style, and it is remembered if you then use the mapping without count.

Using the bang or uppercase mapping will show a list of available styles, and also allow you to change where the docstring will be inserted (above or below the function).

comment boxes

There are 6 different styles for boxes (using mappings from example):

style	mapping	effect
'simple'	1,x	a simple box, no frame
'large_simple'	2,x	a large box, no frame
'box'	1,X	a simple box, full frame
'large_box'	2,X	a large box, full frame
'fullbox'	3,X	convert a comment/box to a full box
'fullbox_centered'	4,X	it also centers the first line

fullbox means that the edge on the right is also closed. It only works when boxifying a previous comment, or converting a simpler box.

Credits

vim-doge for some of the regex patterns, and for test templates.