YARD 0.8.0 Released!

Today we release YARD 0.8.0, with tons of new fun features. Every new major version comes with an unprecedented amount of changes, and this time is no different. Some of my favourite features have come along with this release, and they should make documenting significantly easier. Most of the new goodies are documented in the “What’s New?” file in our docs, but here are some of the highlights:

“Macros” Completely Revamped; Introducing Directives

In 0.7.x, @method and @attribute tags were closely linked with “macros” (we had a @macro tag too), but they were a mess of conflation. YARD 0.8.0 introduces a new “directives” tag and syntax (“@!tagname” instead of “@tagname” to indicate a directive from a meta-data tag) and can act directly on the parser state rather than simply adding data to an object. This is why we call them “behavioural tags”, because they can modify behaviour of both the parser and your documentation. These tags are now properly defined under an API that is both consistent across all handlers (even CRuby code can use these directives, when they previously could not) and extensible by plugin developers (you can write your own directives quite easily).

The @method and @attribute tags were also limited to creating one method per docstring, which means you were very limited in creating objects. The new directive infrastructure allows you to add as many @!method or @!attribute tags to a docstring as you want:

# @!method foo(a, b, c)
# @!method bar(x, y, z)
# Docstring for both methods
define_methods :foo, :bar

In addition to this, free-standing comments can now be parsed, meaning you can add directive tags without having to attach it to Ruby source, allowing you to create method or attribute objects for code that may be hard for YARD to properly parse. As a kicker, we added a “@!parse” directive, which allows you to have YARD parse any arbitrary block of code as if it were literally in your source (but might not be in a parseable form). For instance, you could simplify an “instance_eval” block for documentation, if you wanted:

# @!parse 
#   # Documentation for foo here
#   # @return [Fixnum] the result from {#parent_object}
#   def foo(a, b, c) parent_object.foo(a, b + 1, c + 2) end
instance_eval <<-eof
  def #{methname}(a,b,c)
    parent_object.#{methname}(a, b + 1, c + 2)
  end
eof

It’s not completely DRY, but at least you can get your methods recognized! Note that you could also use @!method to do the same thing, here, but @!parse can parse non-method declaration functionality too (like “include” calls).

Support for Embedding Mixins into Class Documentation (--embed-mixin(s))

You can now use --embed-mixin to embed a mixin by name or --embed-mixins to embed all mixins into the class documentation of where they are included. This allows you to refactor methods out into modules without worrying that they will no longer show up in the right place in your docs (as inherited methods rather than first-class citizens in the class documentation). Rails is a good example of where this might be useful, since they refactor all of their functionality into methods, and even they know this makes documentation harder to find. You can see some embedded mixin docs in YARD’s own documentation in the YARD::Templates::Template module.

I18n Support

We are beginning work on allowing documentation writers to write documentation in multiple languages via gettext support. It’s not all there yet, namely we have yet to translate our own templates to be I18n friendly, but documentation writers can use the new yard i18n command to generate “.pot” files for translation to multiple languages. We will be incrementally improving support for I18n support throughout 0.8.x, and eventually this will be a much more seamless process for documentation writers.

A huge thanks goes out to our Japanese friends, Kouhei Sutou (@kou) et al, for getting this code into YARD!

Greatly Improved Tag Documentation

One of the common frustrations for new users to YARD is the number of tags available, knowing about which ones to use, and how to use them. This was always a concern, and with 0.8.0 we have introduced a completely rewritten “Tags Overview” document that describes every single tag in detail along with at least one very specific example of its usage. We also describe the syntax of tags and what exactly the syntax for each specific tag is. It’s still not perfect, but it should be a huge step up from the previous documentation! We even took advantage of YARD’s template customization to make custom menus for the Tag list in the navigation bar and in the frames version, as well as a listing in the alphabetic index page, just so visibility is not an issue. We will be tackling the markup syntax documentation in the next release.

That’s Not Even All!

Remember, there is tons more new stuff! You should check out the “What’s New?” document for all of it.

Installing YARD

As usual, you can install YARD with:

$ [sudo] gem install yard

Documentation is available at http://rubydoc.org/docs/yard and on the website http://yardoc.org.

Enjoy!