YARD - Code Metadata And Documentation Generation for Ruby
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
contents = contents.read if respond_to? :read
contentsparameter shows how to add type hints to the method argument. The argument can either be a
String, or any class with a
#readmethod (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.
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::Baseclass, and overriding the
processclass, 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
.yardocdatabase which caches the gathered code structure and data. YARD's
yritool, which works like
riand 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
@tagof Javadoc or YARD, but it's indexed and used for documentation and to help IntelliSense (Screencast describing how to help IntelliSense with Type Assertions).
Change the language, not the documentation style
For example, let's say we implement some form of Duby, with annotations to boot. You'll end up with something like this:
def reverse(String contents) => String
Meaning contents is a String, and the method returns a String. In addition to making it easier for document generators, it provides additional, inspectible metadata for that method.
Note that I'm not even suggesting that the argument type be enforced. It could be strictly for document generation, or it could merely emit a warning or whatever we want it to do.
Tom Gilb & Kai Gilb Jan 26, 2015