(Fully) Document your DataMapper models with YARD
2010 / 01 / 16 — datamapper, docs, rdoc, ruby, 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.
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.http://github.com/lsegal/yard
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 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
$ sudo gem install yard-dm
$ cd dm-project/ $ yardoc
It's that easy.