(Fully) Document your DataMapper models with YARD

Any release quality software has to provide documentation, for the future maintainers and other developers. Traditionally, Ruby projects would use RDoc and add custom documentation blurbs to their classes, methods, attributes and constants. Unfortunately, there's a major limitation to RDoc, I can't be extended to recognize new meta-programming method calls.

This rigidness of RDoc really shows up when you need to document ORM backed projects, such as one containing DataMapper models. DataMapper allows one to define the properties and relations between models using handy class-methods:

class MyModel

  include DataMapper::Resource

  # The primary key of the model
  property :id, Serial

  # The name of the model
  property :name, String

  # The many authors contributing to the model
  has n, :authors

  # The user that owns the model
  belongs_to :user

end

RDoc will not recognize property, has or belongs_to. Nor will RDoc know that property adds a class-method and instance reader/writer methods with the given name to the model. Documentation fail.

Enter YARD

YARD is a documentation generation tool for the Ruby programming language. It enables the user to generate consistent, usable documentation that can be exported to a number of formats very easily, and also supports extending for custom Ruby constructs such as custom class level definitions.

YARD organizes most of it's parsing logic into multiple handlers; essentially classes that inherit YARD::Handlers::Ruby::Base and define a process method. YARD also supports a plugin system, by loading any RubyGems installed on the system that are prefixed with yard- or yard_. Using these two features of YARD, one can easily create a YARD plugin gem containing custom handlers, which YARD can automatically load and use.

yard-dm

yard-dm is a YARD plugin for parsing DataMapper model syntax. The plugin can handle the following statements:

• property :name, Type
• has n, :things
• has 1, :thing
• has 0..n, :things
• has 1..n, :things
• has 2..5, :things
• belongs_to :stuff

Install It

$ sudo gem install yard-dm

Use It

$ cd dm-project/
$ yardoc

It's that easy.

Next time you need complete documentation on your DataMapper backed project, just install YARD and yard-dm.