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
- FAQ
- Help
- Contributing
- 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 :tada:
Is your favorite doc standard not supported?
Suggest a new doc standard :tada:, Language, Doc standards, :-----------------, :---------------------------------------------, :---------------------------------------------------------------------------, :white_check_mark:, Python, reST, Numpy, Google, Sphinx, :white_check_mark:, PHP, phpdoc, :white_check_mark:, JavaScript (Including: ES6, FlowJS and NodeJS), JSDoc, :white_check_mark:, TypeScript, JSDoc, :white_check_mark:, CoffeeScript, JSDoc, :white_check_mark:, Lua, LDoc, :white_check_mark:, Java, JavaDoc, :white_check_mark:, Groovy, JavaDoc, :white_check_mark:, Ruby, YARD, :white_check_mark:, Scala, ScalaDoc, :white_check_mark:, Kotlin, KDoc, :white_check_mark:, R, Roxygen2, :white_check_mark:, C++, Doxygen, :white_check_mark:, C, Doxygen, KernelDoc, :white_check_mark:, Shell, Google, # Getting started
Install DoGe:
Using vim-pack:
git clone --depth 1 https://github.com/kkoomen/vim-doge ~/.vim/pack/*/start/vim-doge
Using pathogen:
git clone --depth 1 https://github.com/kkoomen/vim-doge ~/.vim/bundle/vim-doge
Using plug:
Plug 'kkoomen/vim-doge'
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 :tada:
Example:
let g:doge_doc_standard_python = 'numpy'
If you want to change the doc standard specifically for a buffer you can do:
" Inside test.py
:let b:doge_doc_standard = '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_coffeescript, '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_scala, 'scaladoc', 'scaladoc', g:doge_doc_standard_kotlin, 'kdoc', 'kdoc', g:doge_doc_standard_r, 'roxygen2', 'roxygen2', g:doge_doc_standard_cpp, 'doxygen_javadoc', 'doxygen_javadoc', 'doxygen_javadoc_no_asterisk', 'doxygen_javadoc_banner', 'doxygen_qt', 'doxygen_qt_no_asterisk', g:doge_doc_standard_c, 'doxygen_javadoc', 'kernel_doc', 'doxygen_javadoc', 'doxygen_javadoc_no_asterisk', 'doxygen_javadoc_banner', 'doxygen_qt', 'doxygen_qt_no_asterisk', g:doge_doc_standard_sh, 'google', 'google', ## 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',
],
'java': ['groovy'],
}
Set filetypes as an alias for other filetypes. The key should be the filetype
that is defined in ftplugin/<key>.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 next 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 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.
:DogeCreateDocStandard {doc_standard}
Command to generate a custom doc standard template. The {doc_standard} is a
mandatory argument which is the name of the new doc standard. If it exists, the
existing doc standard with the same name will be used as base for the custom
template. It can complete the available doc standards for the current buffer.
For more information on how to create custom doc standards you can read
Writing your first pattern.
FAQ
Using C / C++
If you use a language that belongs to the C-family then you have to use clang.
This is the parser that is being used for generating proper documentation.
Prerequisites
- Vim requires to be compiled with python 3.
- Python 3.5+
pip3 install clang
Adding additional clang args
The Python binding for clang allows additional arguments. These arguments can be
set with g:doge_clang_args. For example:
let g:doge_clang_args = ['-I', '/my/include/path']
Package manager
If you've installed clang via your package manager then you might have a file
called libclang.so.<libclang-major-version> somewhere in your system, for
example: /usr/lib/libclang.so.8. Go into the directory where this file exists
using cd and create a symlink:
cd /usr/lib/
ln -s libclang.so.8 libclang.so
Now it should be detectable via python if you do:
$ python3
>>> from clang.cindex import Index
>>> Index.create()
>>> <clang.cindex.Index object at 0x1084763d0>
Manual compiling
If you compiled libclang manually, then make sure that your $PATH and
$LD_LIBRARY_PATH are set correctly.
The libclang binary its location should be defined in the $LD_LIBRARY_PATH:
# MacOS
export LD_LIBRARY_PATH="/Library/Developer/CommandLineTools/usr/lib/"
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.
Motivation
I created DoGe mainly because I couldn't find a plugin that could generate
proper comments for a big collection of languages in a quick and easy way. I am
a polyglot developer when it comes to programming languages and I couldn't find
proper vim plugins that would generate documentation quickly for all languages I
did want to be supported.
Rather then 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.