ActiveDoc
DSL for code description. It allows to create ‘executable documentation’.
Synopsis
class Mailer
include ActiveDoc
takes :to, /^[a-z.]+@[a-z.]+\.[a-z]+$/, :desc => "Receiver address"
def send(to)
#...
end
end
Mailer.new.send("[email protected]") # => ok
Mailer.new.send("fake.address.org") # => raises ArgumentError
Features
-
Describe code with code
-
Generate RDoc comments
-
DRY your documentation
-
Hash arguments description
-
Really up-to-date
Installation
gem install active_doc --pre
To use rake task, put something like this to your Rakefile
require 'rubygems'
require 'bundler'
Bundler.setup
require 'active_doc/rake/task'
ActiveDoc::Rake::Task.new do
# here you can put additional requirement files
require File.("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 typeString
-
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 {|args| args[:number] != 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. Compatibility with 1.8.7 to be fixed in future releases.
Usage Notice
Bear in mind: This gem is in early-stages of development and was not sufficiently tested in external projects.
Road Map
-
Support for 1.8.7
-
Combine argument expectations with AND and OR conjunctions
-
More types of descriptions (for modules, mixins…)
Contribution
Every bug report, bug fix, feature request or already implemented feature is welcome.
To report a bug or request a feature, create an issue in Github.
When contributing, please follow following instructions:
-
Write spec for your contribution. It ensures everything works in future.
-
Do not bother with Rakefile, version or history. It’s OK to have your own, but if so, keep it in separated commit
to be easily ignored, when pulling.
-
Bonus points for topic branch.
NOTICE: I am quite new to open source development, so I appreciate every input from more experienced contributor. Contact me on e-mail.
Copyright
Copyright © 2011 Ivan Nečas. See LICENSE for details.