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 <C-d>(Ctrl + d), jump quickly
through TODO items using <Tab> and <S-Tab> to quickly add descriptions and
go on coding!
- Table of Contents
- Supported languages and doc standards
- Getting started
- Configuration
- Help
- FAQ
- Contributing
- Motivation
- Supporting DoGe
- License
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 standard | |
|---|---|---|
| ✅ | Python | reST, Numpy |
| ✅ | PHP | phpdoc |
| ✅ | JavaScript (Including: ES6, FlowJS and NodeJS) | JSDoc |
| ✅ | TypeScript | JSDoc |
| ✅ | CoffeeScript | JSDoc |
| ✅ | Lua | LDoc |
| ✅ | Java | JavaDoc |
| ✅ | Groovy | JavaDoc |
| ✅ | Ruby | YARD |
| ✅ | Scala | ScalaDoc |
| ✅ | Kotlin | KDoc |
| ✅ | R | Roxygen2 |
| ✅ | C++ | Doxygen |
Install DoGe:
Using vim-pack:
git clone https://github.com/kkoomen/vim-doge ~/.vim/pack/*/start/vim-doge
Using pathogen:
git clone https://github.com/kkoomen/vim-doge ~/.vim/bundle/vim-doge
Using plug:
Plug 'kkoomen/vim-doge'
Run :help doge to get the full help page.
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'Here is the full list of available doc standards per filetype:
| Variable | Default | Supported |
|---|---|---|
g:doge_doc_standard_python |
'reST' |
'reST', 'numpy' |
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' |
'doxygen' |
Default: '<C-d>'
The mapping to trigger DoGe.
Default: '<Tab>'
The mapping to jump forward to the next TODO item in a comment. Requires
g:doge_comment_interactive to be enabled.
Default: '<S-Tab>'
The mapping to jump backward to the next TODO item in a comment. Requires
g:doge_comment_interactive to be enabled.
Default: 1
Adds the TODO suffix after every generated parameter.
Default: 1
Jumps interactively through all TODO items in the generated comment.
To open all the help pages, run :help doge.
Problem:
This is because you have another plugin that overrides the DoGe default <Tab>
mapping in select mode. UltiSnips could be one of them for most people or any
other plugin that maps the <Tab> character in select mode.
Solution:
You can solve this by re-mapping the jump forward/backward keys using
g:doge_mapping_comment_jump_forward and g:doge_mapping_comment_jump_backward
or re-map the other plugins. You can also load DoGe earlier since it uses nore
and thus should prevent other plugins from overwriting at a later stage.
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.
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.
Do you enjoy using DoGe? Give it a star on GitHub and submit your vote on vim.org.
DoGe is licensed under the GPL-3.0 license.