/vim-yardoc

Ruby syntax extensions for highlighting YARD documentation.

Primary LanguageVimL

vim-yardoc

This plugin provides Ruby syntax extensions for highlighting YARD documentation. In contrast with vim-yard, vim-yardoc piggy backs on Vim's existing Ruby syntax to provide an integrated experience.

Contents

  1. Installation
  2. Usage
  1. Contributing

Installation

Assuming this isn't your first rodeo there are three approaches to installing vim-yardoc.

With pathogen

If you're not already using Tim Pope's fantastic pathogen plugin, I would highly encourage you to do so. If you are, you're probably not even reading this. However, in the event you are reading this, the instructions are as follows:

% cd ~/.vim/bundle
% git clone https://github.com/noprompt/vim-yardoc.git

Without pathogen

Install the pathogen plugin. See these instructions.

With vundle

Drop the following line in your .vimrc:

Bundle 'noprompt/vim-yardoc'

save it and either source it or reopen vim, after that type :BundleInstall in command mode to just install the added bundle or :BundleInstall! to update all other bundles and install the new one.

Close and reopen vim and you are done.

By hand

Clone this repo to a location on your computer.

% git clone https://github.com/noprompt/vim-yardoc.git /somewhere/vim-yardoc

Next, check to make sure you don't already have a ruby.vim file in ~/.vim/after/syntax like so:

% test -f ~/.vim/syntax/after/ruby.vim
% echo $?

If 1 is printed, you're good to copy the file:

% cp vim-yard/after/syntax/ruby.vim ~/.vim/syntax/after/ruby.vim

If 0 is printed, you can copy the contents of vim-yardoc/after/syntax/ruby.vim to your existing Ruby syntax extensions file:

% echo -e "\n\" BEGIN vim-yardoc {{{" >> ~/.vim/syntax/after/ruby.vim
% cat vim-yardoc/after/syntax/ruby.vim >> ~/.vim/syntax/after/ruby.vim
% echo -e "\n\" END vim-yardoc }}}" >> ~/.vim/syntax/after/ruby.vim

You do not need to run the first and last commands, however, it may serve as a helpful marker in the future should you choose to edit the file again.

Usage

This "plugin" merely provides extensions to Vim's Ruby syntax and changes almost nothing in terms of the appearence of your Ruby documents. With the exception of YARD tags and directives , which are linked to rubyTodo, all yard related syntax groups are linked to Comment. You may find yourself somewhat underwhelmed after installing it. This is intentional but, fear not, there are two good reasons for this posture.

The first reason is the desire to avoid making assumptions about which syntax groups should link to others. Since viturally nothing can be known about your particular configuration, except you're likely to have a Ruby syntax file in your $VIMRUNTIME directory, highlight links are only made against Comment and rubyTodo (as noted above).

The second reason, in tandem with the first, is the desire to leave customization entirely up to you. This might be a bit off-putting for some but having the flexibility to customize an experience you enjoy is certainly more valuable than forcing you to customize one you do not. In some cases "sensible defaults" simply do not exist.

Customization

You can add your own custom highlight links to either your .vimrc file or to your current theme. For instance, you might like YARD tags to look like to look like instance variables (since both begin with an @ symbol):

hi link yardGenericTag rubyInstanceVariable

It's really quite painless.

Syntax groups

The following syntax groups are available for customization:

Tags (as listed here)

yardGenericTag
yardAbstract
yardApi
yardAttr
yardAttrReader
yardAttrWriter
yardAuthor
yardDeprecated
yardExample
yardNote
yardOption
yardOverload
yardParam
yardPrivate
yardRaise
yardReturn
yardSee
yardSince
yardTodo
yardVersion
yardYield
yardYieldParam
yardYieldReturn

Directives (as listed here)

yardGenericDirective
yardAttribute
yardEndGroup
yardGroup
yardMacro
yardMethod
yardParse
yardScope
yardVisibility

Types, Lists, and Hashes (as specified here)

yardDuckType
yardType
yardLiteral
yardOrderDependentList
yardParametricType
yardTypeList
yardHashAngle
yardHashCurly

Delimiters

yardComma
yardArrow

Contributing

Contributions and feedback are almost certainly encouraged. This is my first shot at writing syntax extensions for Vim so any assistence or suggestion is happily welcomed.