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)
- 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.
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
The flexibility comes from the usage of bang
and count
in both mappings and
commands.
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).
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.
vim-doge for some of the regex patterns, and for test templates.