YARD - Code Metadata And Documentation Generation for Ruby

In his talk at RubyFringe, Merb contributor and EngineYard employee Yehuda Katz mentioned a few tools to watch in the future. One of the tools is the documentation generation tool YARD, which allows to add metadata to Ruby documentation, among other features. YARD is designed to play well with RDoc formatted doc strings, but allows to use different markup notations. YARD is extensible, allowing to plug in custom handlers for code constructs and different output backends.

One distinguishing feature is the support for metadata in comment strings. Users of tools like Javadoc will find the meta tag notation familiar (from the YARD Readme):

# Reverses the contents of a String or IO object. 
# 
# @param [String, #read] contents the contents to reverse 
# @return [String] the contents reversed lexically  
def reverse(contents)    
 contents = contents.read if respond_to? :read
 contents.reverse   
end 

The contents parameter shows how to add type hints to the method argument. The argument can either be a String, or any class with a #read method (InfoQ previously discussed different approaches to type annotations in relation to protocols and duck typing).

Both RDoc 2.1 and YARD provide ways to document metaprogrammed methods. With RDoc, a comment starting with "##" defines a comment for a metaprogrammed method. The heuristic is to ignore the identifier immediately following the comment and take the following token as the method name:

## 
# Does stuff. 
add_method :foo 

Methods that don't actually appear in the source code, but are part of the class interface can be documented like this:

##
# :method invisible_method 

YARD is built with pluggable handlers - in fact, the basic functionality is implemented as handlers. A new handler can be added by extending the YARD::Handlers::Base class, and overriding the process class, which allows to write handlers for custom constructs, such as internal DSLs or behavior similar to RDoc's solutions.

Running YARD on a project creates a .yardoc database which caches the gathered code structure and data. YARD's yri tool, which works like ri and uses this database to allow for interactive documentation lookup. YARD can also use the cached information in the database to generate output in multiple formats, without having to analyze the repeatedly. YARD's cache is similar to code indexes created by IDEs to allow for advanced code search (i.e. searching for language constructs, not just fulltext search), code browsing, or for refactoring tools that need to be aware of all code in a project.

The idea to provide metadata about methods in comments has been around for some time in the Ruby space. Some projects promote optional type annotations in comments. Merb, for instance, has the following documentation guideline:

All methods (public and private) are required to provide a clear method signature, including the types for any parameters, and the possible values for any options hashes, as well as return types and other information.

Merb currently uses a different notation to specify the method signature.

Another approach is supported in SapphireSteel's Ruby In Steel IDE: Type Assertions The metadata uses a different format than the @tag of Javadoc or YARD, but it's indexed and used for documentation and to help IntelliSense (Screencast describing how to help IntelliSense with Type Assertions).