= ActiveDoc

DSL for code description. It allows to create 'executable documentation' and to design by contract.

== Synopsis

class Mailer include ActiveDoc

takes :to, /^[a-z.]+@[a-z.]+.[a-z]+$/, :desc => "Receiver address" def send_mail(to)

...

end end

Mailer.new.send_mail("[email protected]") # => ok Mailer.new.send_mail("fake.address.org") # => raises ArgumentError

== Features

• Describe code with code

• Generate RDoc comments

• DRY your documentation

• Hash arguments description

• Really up-to-date

== Requirements

• Ruby 1.9.2

== Installation

gem install active_doc

To use rake task, put something like this to your Rakefile

require 'rubygems' require 'bundler' Bundler.setup

require 'active_doc/rake/task'

in_dir = File.expand_path("../lib", FILE) out_dir = File.expand_path("../active_doc_out", FILE) ActiveDoc::Rake::Task.new(in_dir, out_dir) do

here you can put additional requirement files

require File.expand_path("lib/phone_book.rb", File.dirname(FILE)) end

This adds task +active_doc+ to generate RDoc comments from ActiveDoc.

== Usage

To use ActiveDoc DSL in your class: include ActiveDoc

=== Method Arguments Description

Validations based on descriptions are checked every time the method is called.

When generating RDoc comments, the space between last argument description and method definition is used:

takes :name, String

==== Arguments:

* +name+ :: (String)

def say_hallo_to(name) ... end

NOTICE: anything else in this space will be replaced.

==== Describe by Type:

takes :name, String def say_hallo_to(name) ... end

• Validation: :: Raises ArgumentError, when +name+ is not of type +String+

• RDoc:

  ==== Arguments:

  * +name+ :: (String)

==== Describe by Duck Type:

takes :name, :duck => :upcase def say_hallo_to(name) ... end

• Validation: :: Raises ArgumentError, when +name+ does not respond to +:upcase+

• RDoc:

  ==== Arguments:

  * +name+ :: (respond to :upcase)

==== Describe by Regexp:

takes :phone_number, /^[0-9]{9}$/ def call_to(phone_number) ... end

• Validation: :: Raises ArgumentError, when regexp does not match +phone_number+

• RDoc:

  ==== Arguments:

  * +phone_number+ :: (/^[0-9]{9}$/)

==== Describe by Enumeration:

takes :position, [:start, :middle, :end] def jump_to(position) ... end

• Validation: :: Raises ArgumentError, when positions is not included in [:start, :middle, :end]

• RDoc:

  ==== Arguments:

  * +position+ :: ([:start, :middle, :end])

==== Describe Options Hash:

takes :options, Hash do takes :format, [:csv, :ods, :xls] end def export(options) ... end

• Validation: :: Raises ArgumentError, when:
  • +options[:format]+ is not included in [:csv, :ods, :xls]
  • +options+ contains a key not mentioned in argument description

This differs from describing method arguments, where argument description is optional. Here it's required. The reason is to prevent from (perhaps mistakenly) passing unexpected option.

• RDoc:

  ==== Arguments:

  * +options+:

  * +:format+ :: ([:csv, :ods, :xls])

==== Describe by Proc: When passing proc taking an argument, this proc is used to validate value of this method argument.

takes :number {|value| value != 0} def divide(number) ... end

• Validation: :: Raises ArgumentError, unless proc.call(position)

• RDoc:

  ==== Arguments:

  * +number+ :: (Complex Condition)

=== Compatibility

This version was tested on and should be compatible with Ruby 1.9.2. It uses some features introduced in Ruby 1.9. It's not compatible with 1.8.7 and since 1.8.7 starts being legacy there isn't plan to support it unless you implement it.

=== Usage Notice Bear in mind: This gem is in early-stages of development and was not sufficiently tested in external projects.

=== Road Map

• Combine argument expectations with AND and OR conjunctions
• More types of descriptions (for modules, mixins...)

=== Contribution

Welcome

== Copyright

Copyright (c) 2011 Ivan Nečas. See LICENSE for details.