kkoomen/vim-doge at v1.15.0

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!

Visit the demo page

Table of Contents

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
	CoffeeScript	JSDoc
	Lua	LDoc
	Java	JavaDoc
	Groovy	JavaDoc
	Ruby	YARD
	Scala	ScalaDoc
	Kotlin	KDoc
	R	Roxygen2
	C++	Doxygen
	C	Doxygen, KernelDoc

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

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:

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.

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

Command to generate documentation.

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+

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.

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.