Below are some of the main features of YARD.
Yardoc Meta-tag Formatting
YARD uses a '@tag' style definition syntax (like Python, Java, Objective-C and other languages) for meta tags alongside regular code documentation. These tags should be able to happily sit side by side RDoc formatted documentation, but provide a much more consistent and usable way to describe important information about objects, such as what parameters they take and what types they are expected to be, what type a method should return, what exceptions it can raise, if it is deprecated, etc.. It also allows information to be better (and more consistently) organizedduring the output generation phase. You can find a list of tags in the Tags.md file.
YARD also supports an optional "types" declarations for certain tags. This allows the developer to document type signatures for ruby methods and parameters in a non intrusive but helpful and consistent manner. Instead of describing this data in the body of the description, a developer may formally declare the parameter or return type(s) in a single line. Consider the following Yardoc'd method:
# 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
With the above @param tag, we learn that the contents parameter can either be a String or any object that responds to the 'read' method, which is more powerful than the textual description, which says it should be an IO object. This also informs the developer that they should expect to receive a String object returned by the method, and although this may be obvious for a 'reverse' method, it becomes very useful when the method name may not be as descriptive.
RDoc Formatting Compatibility
YARD is made to be compatiblewith RDoc formatting. In fact, YARD does no processing on RDoc documentation strings, and leaves this up to the output generation tool to decide how to render the documentation.
A Local Documentation Server
YARD can serve documentation for projects or installed gems (similar to
gem server) with the added benefit of dynamic searching, as well as live
reloading. Using the live reload feature, you can document your code and
immediately preview the results by refreshing the page; YARD will do all the
work in re-generating the HTML. This makes writing documentation a much
Custom Constructs and Extensibility
YARD is designed to be extended and customized by plugins. Take for instance the scenario where you need to document the following code:
# Sets the publisher name for the list. cattr_accessor :publisher
This custom declaration provides dynamically generated code that is hard for a
documentation tool to properly document without help from the developer. To
ease the pains of manually documenting the procedure, YARD can be extended by
the developer to handle the
cattr_accessor construct and automatically create
an attribute on the class with the associated documentation. This makes
documenting external API's, especially dynamic ones, a lot more consistent for
consumption by the users.
YARD is also designed for extensibility everywhere else, allowing you to add support for new programming languages, new data structures and even where/how data is stored.
YARD makes it easy to customize templates using a specially designed templating system. The design allows plugin developers to make small modifications to a template without breaking changes that may have been made from another plugin. This means you can install multiple plugins that each make independent modifications without running into problems with your template. It also allows you to easily make small changes (like adding your own stylesheets) without digging into any markup.
Raw Data Output
YARD also outputs documented objects as raw data (the dumped Namespace) which can be reloaded to do generation at a later date, or even auditing on code. This means that any developer can use the raw data to perform output generation for any custom format, such as YAML, for instance. While YARD plans to support XHTML style documentation output as well as command line (text based) and possibly XML, this may still be useful for those who would like to reap the benefits of YARD's processing in other forms, such as throwing all the documentation into a database. Another useful way of exploiting this raw data format would be to write tools that can auto generate test cases, for example, or show possible unhandled exceptions in code.