Any fool can write code that a computer can understand. Good programmers write code that humans can understand. -- Martin Fowler, 1999
We all love documentation because it makes our codebases easier to understand, yet no one has time to write it in a good and proper way.
DoGe is a (Do)cumentation (Ge)nerator which will generate a proper documentation
skeleton based on certain expressions (mainly functions). Simply put your cursor
on a function, press <Leader>d
, jump quickly through TODO
items using
<Tab>
and <S-Tab>
to quickly add descriptions and go on coding!
Table of Contents
- Table of Contents
- Supported languages and doc standards
- Getting started
- Configuration
- Commands
- Language-specific configuration
- Headless mode
- Help
- Contributing
- Development
- Motivation
- Supporting DoGe
- License
Supported languages and doc standards
Every language that has a documentation standard should be supported by DoGe.
Is your favorite language not supported?
Suggest a new language
Is your favorite doc standard not supported?
Suggest a new doc standard
Language | Doc standards | |
---|---|---|
Python | reST, Numpy, Google, Sphinx | |
PHP | phpdoc | |
JavaScript (Including: ES6, FlowJS and NodeJS) | JSDoc | |
β | TypeScript | JSDoc |
β | Lua | LDoc |
β | Java | JavaDoc |
β | Groovy | JavaDoc |
Ruby | YARD | |
β | C++ | Doxygen |
β | C | Doxygen, KernelDoc |
C# | XMLDoc | |
Bash | ||
β | Rust | RustDoc |
Getting started
npm i --no-save && npm run build:binary:unix
. If you're using vim-plug, you
can do:
Plug 'kkoomen/vim-doge', { 'do': 'npm i --no-save && npm run build:binary:unix' }
Using plug:
Plug 'kkoomen/vim-doge', { 'do': { -> doge#install() } }
Using vim-pack:
git clone --recursive --depth 1 https://github.com/kkoomen/vim-doge ~/.vim/pack/*/start/vim-doge
- Open Vim and run
:call doge#install()
Using Pathogen:
git clone --recursive --depth 1 https://github.com/kkoomen/vim-doge ~/.vim/bundle/vim-doge
- Open Vim and run
:call doge#install()
Using Vundle:
Plugin 'kkoomen/vim-doge'
- Open Vim and run
:call doge#install()
Configuration
Run :help doge
to get the full help page.
Choosing a different doc standard
DoGe supports multiple doc standard and you can overwrite them per filetype in
your vimrc. Is your favorite doc standard not supported?
Suggest a new doc standard
Example:
let g:doge_doc_standard_python = 'numpy'
If you want to change the doc standard specifically for a buffer, then you can do:
" Inside test.py
:let b:doge_doc_standard = 'numpy'
If you want to generate a docblock using a different doc standard just for a
specific expression, then you can use DogeGenerate
:
" Inside test.py, cursor is at a function expression (cursor = `|`):
" |def foo(p1, p2):
" pass
:DogeGenerate numpy
Here is the full list of available doc standards per filetype:
Variable | Default | Supported |
---|---|---|
g:doge_doc_standard_python |
'reST' |
'reST' , 'numpy' , 'google' , 'sphinx' |
g:doge_doc_standard_php |
'phpdoc' |
'phpdoc' |
g:doge_doc_standard_javascript |
'jsdoc' |
'jsdoc' |
g:doge_doc_standard_typescript |
'jsdoc' |
'jsdoc' |
g:doge_doc_standard_lua |
'ldoc' |
'ldoc' |
g:doge_doc_standard_java |
'javadoc' |
'javadoc' |
g:doge_doc_standard_groovy |
'javadoc' |
'javadoc' |
g:doge_doc_standard_ruby |
'YARD' |
'YARD' |
g:doge_doc_standard_cpp |
'doxygen_javadoc' |
'doxygen_javadoc' , 'doxygen_javadoc_no_asterisk' , 'doxygen_javadoc_banner' , 'doxygen_qt' , 'doxygen_qt_no_asterisk' , 'doxygen_cpp_comment_slash' , 'doxygen_cpp_comment_exclamation' , 'doxygen_cpp_comment_slash_banner' |
g:doge_doc_standard_c |
'doxygen_javadoc' |
'kernel_doc' , 'doxygen_javadoc' , 'doxygen_javadoc_no_asterisk' , 'doxygen_javadoc_banner' , 'doxygen_qt' , 'doxygen_qt_no_asterisk' , 'doxygen_cpp_comment_slash' , 'doxygen_cpp_comment_exclamation' , 'doxygen_cpp_comment_slash_banner' |
g:doge_doc_standard_sh |
'google' |
'google' |
g:doge_doc_standard_rs |
'rustdoc' |
'rustdoc' |
g:doge_doc_standard_cs |
'xmldoc' |
'xmldoc' |
Options
g:doge_enable_mappings
Default: 1
Whether or not to enable built-in mappings.
g:doge_mapping
Default: '<Leader>d'
The mapping to trigger DoGe. The mapping accepts a count, to select a specific doc standard, if more than one is defined.
g:doge_filetype_aliases
Default:
{
'javascript': [
'javascript.jsx',
'javascriptreact',
'javascript.tsx',
'typescriptreact',
'typescript',
'typescript.tsx',
],
'java': ['groovy'],
}
Set filetypes as an alias for other filetypes. The key should be the filetype
that is defined in ftplugin/<filetype>.vim
. The value must be a list of 1 or
more filetypes that will be aliases.
Example:
let g:doge_filetype_aliases = {
\ 'javascript': ['vue']
\}
If you use the above settings and you open myfile.vue
then it will behave like
you're opening a JavaScript filetype.
g:doge_buffer_mappings
Default: 1
Mappings to jump forward/backward are applied as buffer mappings when interactive mode starts and removed when it ends.
g:doge_mapping_comment_jump_forward
Default: '<Tab>'
The mapping to jump forward to the next TODO
item in a comment. Requires
g:doge_comment_interactive
to be enabled.
g:doge_mapping_comment_jump_backward
Default: '<S-Tab>'
The mapping to jump backward to the previous TODO
item in a comment. Requires
g:doge_comment_interactive
to be enabled.
g:doge_comment_interactive
Default: 1
Jumps interactively through all TODO
items in the generated comment.
g:doge_comment_jump_wrap
Default: 1
Continue to cycle among placeholders when reaching the start or end.
g:doge_comment_jump_modes
Default: ['n', 'i', 's']
Defines the modes in which doge will jump forward and backward when interactive
mode is active. For example: removing i
would allow you to use <Tab>
for
autocompletion in insert mode.
Commands
:DogeGenerate {doc_standard}
Command to generate documentation. The {doc_standard}
accepts a count or a
string as argument, and it can complete the available doc standards for the
current buffer.
The numeric value should point to an index key from the
b:doge_supported_doc_standards
variable.
The string value should point to a doc standard name listed in the
b:doge_supported_doc_standards
variable.
Language-specific configuration
Below is a list of language-specific configuration and their default values.
JavaScript
JavaScript settings automatically apply for all the default filetypes that are
being aliased, see g:doge_filetype_aliases
.
let g:doge_javascript_settings = {
\ 'destructuring_props': 1,
\ 'omit_redundant_param_types': 0,
\}
-
destructuring_props
: Whether or not to generate@param
tags for the destructured properties in a function expression. -
omit_redundant_param_types
: Whether or not to omit the{type}
part of parameters and return types when the type is known (i.e. typescript).
PHP
let g:doge_php_settings = {
\ 'resolve_fqn': 1
\}
resolve_fqn
: Whether or not to resolve the FQN based on theuse
statements in the current buffer. The FQN will be resolved for type hints in parameters and the return type.
Python
let g:doge_python_settings = {
\ 'single_quotes': 0
\}
single_quotes
: Whether or not to use single quotes for the multi-line comments openers and closers.
Headless mode
If you're running your vim commands inside a docker, CI or similar environments
with commands such as vim +PlugInstall +qall > /dev/null
then you probably
want to use headless mode. This will not spawn any terminals, progress bars etc
and will simply run any process by vim-doge in the background.
This feature can be enabled by passing in { 'headless': 1 }
into the
doge#install()
like so: doge#install({ 'headless': 1 })
.
Example using vim-plug:
Plug 'kkoomen/vim-doge', {'do': { -> doge#install({ 'headless': 1 }) }}
Help
To open all the help pages, run :help doge
.
Contributing
Help or feedback is always appreciated. If you find any bugs, feel free to submit a bug report. If you think DoGe can be improved, feel free to submit a feature request or a pull request if you have time to help out.
Read the Contribution Guidelines and Code of Conduct when doing contributions.
Tree sitter
If you want a new language to be supported but tree-sitter doesn't support it yet, then feel free to create a custom tree-sitter language parser for that language and then we'll integrate it into vim-doge.
Development
Environment setup
Get started by simply cd /path/to/vim-doge
and run yarn
.
Parsers
If you want to work on the parsers locally, or anything else that resides in the
src
folder, you can run: yarn watch
.
Testing locally
If you want to run the tests locally, you should install vader at the same directory level that vim-doge is, so your structure should look like this (using vim-plug example):
~/.vim/plugged/
βββ vader.vim
βββ vim-doge
After that, you can do the following:
cd /path/to/vim-doge
vim -u test/vimrc
- Inside vim you can now run:
Vader test/**/**/*.vader
to run all tests
Vader test/filetypes/<filetype>/functions.<ext>
Motivation
I created DoGe mainly because I couldn't find a plugin that could generate proper comments for a big collection of languages that I would use on a daily basis in a quick and easy way.
Rather than scraping off the internet to find all sorts of vim plugins for every language I was coding in, I did want a single plugin that would support every language I was working in.
Another big motivation for me is that I've noticed people tend to skip the documentation part because writing just the skeleton of the comment takes already too much time and I am one of those people. Having the skeleton generated and an interactive mode to quickly add descriptions is a big time saver.
Supporting DoGe
Do you enjoy using DoGe? Give it a star on GitHub and submit your vote on vim.org.
License
DoGe is licensed under the GPL-3.0 license.