YARD 0.4.0 (The Whole Nine) Released Today

YARD 0.4.0 (codenamed The Whole Nine) was just released today. It’s by far the biggest release since I started writing YARD in 2007. For those who don’t know, YARD is a Ruby documentation tool that surpasses the features of RDoc to bring much richer docs and extensibility to documenteurs. There’s plenty of new features to discuss and plenty of new toys to show off (new templates, live doc server with user comments, new APIs, plugin support), so let’s get started.

New Templates & Templating Engine

The old templates were ugly. This time, full attention was put into making the templates both aesthetically pleasing and more informative than the old ones. The unusable, unlinkable frames were removed in favour of a Javascript based menu system with inline search for methods, classes and modules. The look is much cleaner (partly inspired by Apple’s Objective-C and Sproutcore documentation) and much easier to follow. And many more meta-data tags are now properly included in the docs.

{.noborder}

The new templates in action, showing docs for ActiveRecord and the list of classes/modules on the top right.

This template re-design is in part due to the new templating engine introduced in YARD 0.4.0, which allows for much more user customization. This will be important as people start extending YARD to add other meta-data tags or write plugins (also new in YARD). My next blog post will be discussing how to write a plugin that customizes the templates to add extra output without having to redesign everything. Stay tuned for that.

A New Website

YARD’s homepage was redesigned and moved to http://www.yardoc.org. I think the new look is much nicer, but the real kicker here is the new Live Documentation Server, powered by YARD to generated docs on the fly.

A Live Documentation Server, with User Comments!

This isn’t exactly a feature of YARD itself, but a testament to what can be done with YARD. I mentioned the new templating engine gave a much better ability to customize templates than before. The engine is partly what makes the live documentation server on YARD’s homepage possible in order to integrate it with the Sinatra app that powers on-the-fly template generation as well as on-the-fly search.

The live docs also allow for direct links to documentation pages for individual methods (like YARD::Templates::Engine.render) so linking users to specific methods is now much easier. The best feature of all, however, is the brand-spanking-new user comments system powered by DISQUS that is available on these individual method pages, allowing users to contribute extra information about methods in one place. User feedback tends to be key in large projects. This feature is going to change documentation. If there is one thing PHP’s community has over Ruby’s is a pretty great documentation site. Well, now PHP can goto hell; because PHP finally has a goto statement, and Ruby finally has a great documentation site.

{.noborder}

User comments on a documented Ruby method.

If you didn’t find it on the homepage, the docs server is here: http://yardoc.org/docs.

Note that It’s mostly just an alpha-experimental test to see how YARD holds up. Things should break in the first few days; when they do, let me know and they’ll get fixed. If everything works out, we will be merging the service back into the beloved http://rdoc.info.

Other Cool Stuff

1. YARD’s own documentation is now nearly complete. This was kind of an embarrassing truth for the last few years, but YARD’s own documentation was never really up to par. This release should mark a commitment to bettering YARD’s own docs.
2. Generate documentation using meta-data queries. The yardoc tool now has support for a --query argument which can take queries on object meta-data to include or exclude classes/modules/methods based on their data. This means you can now make a query like --query '@api.text == "public"' to document only your public API.
3. A Few New Tags. @private and @abstract were added to YARD’s tag library. @private in particular goes hand in hand with the query feature to allow for RDoc style :nodoc: behaviour. An important note: this is still not recommended practice by YARD. You should be documenting all of your code. The private tag should be added in addition to regular documentation to denote that the class/module/constant or global method is actually in the “private” Ruby visibility, even though Ruby cannot express this (due to visibility limitations on classes, modules and constants). To hide all objects with a private tag you can use the query --query !@private or the equivalent argument --no-private
4. Plugin Support. YARD now auto-loads any gem named with the prefix “yard-“ or “yard_” (with the first prefix being recommended). You can use this autoloading feature to add custom functionality (like handlers or template customizations) to YARD. I will be writing guides on how to do this shortly.

You can read more about all the new features in the what’s new document in YARD’s docs.

So that’s the new release of YARD. Try it out (gem install yard) and start documenting your code. And remember, if you like YARD and use it often, consider donating to make it even better. YARD accepts Pledgie donations:

{.noborder}