active_doc 0.1.0

data/.gitignore

@@ -0,0 +1,2 @@
+Gemfile.lock
+tmp/*

data/Gemfile

@@ -0,0 +1,6 @@
+source "http://rubygems.org"
+
+group :development do
+  gem 'bundler'
+  gem "rspec"
+end

data/History.txt

@@ -0,0 +1,38 @@
+== 0.1.0
+
+=== New features
+* Duck-typing - defining methods for argument to respond_to?
+
+=== TODO:
+* Synopsis for this gem
+* Duck-typing - defining methods for argument to respond_to?
+
+== 0.1.0.beta.4 (2011-03-06)
+
+=== New features
+* Referencing to another definition
+* Specifying argument expectation is not required
+* Raw expectations in block for +takes+
+* Expectation by array of options
+
+== 0.1.0.beta.3 (2011-03-05)
+More options for describing arguments
+
+=== New features
+* Describe argument with regexp
+* Describe hash argument with nested expectations - suitable for options argument
+
+== 0.1.0.beta.2 (2011-03-03)
+Generating RDOC
+
+=== New features
+* Generate rdoc for method descriptions
+* Rake task for generating RDOC
+
+== 0.1.0.beta.1 (2011-03-01)
+
+First gem pre-release!
+
+=== New features
+* arguments descriptions for instance and class methods
+* basic architecture

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License
+
+Copyright (c) 2011 Ivan Nečas
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,202 @@
+= 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("address@example.com") # => 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.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
+
+<b>NOTICE: anything else in this space will be replaced.</b>
+
+==== 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 {|args| args[:number] != 0}
+ def divide(number)
+  ...
+ end
+
+* Validation: :: Raises ArgumentError, unless proc.call(position)
+
+* RDoc:
+ # ==== Arguments:
+ # * +number+ :: (Complex Condition)
+
+=== Compatibility
+
+<b> 
+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.
+</b>
+
+=== Usage Notice
+<b>
+Bear in mind: This gem is in early-stages of development and was not sufficiently tested in external projects.
+</b>
+
+=== 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.
+
+<b>
+NOTICE: I am quite new to open source development, so I appreciate every input from more experienced contributor.
+Contact me on e-mail.
+</b>
+
+
+
+
+== Copyright
+
+Copyright (c) 2011 Ivan Nečas. See LICENSE for details.
+

data/active_doc.gemspec

@@ -0,0 +1,32 @@
+# -*- encoding: utf-8 -*-
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+require "active_doc"
+
+Gem::Specification.new do |s|
+  s.name        = 'active_doc'
+  s.version     = ActiveDoc::VERSION
+  s.authors     = ["Ivan Nečas"]
+  s.description = 'DSL for executable documentation of your code.'
+  s.summary     = "active_doc-#{s.version}"
+  s.email       = 'necasik@gmail.com'
+  s.homepage    = "http://github.com/necasik/active_doc"
+
+  s.post_install_message = %{
+(::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::)
+
+Thank you for installing active_doc-#{ActiveDoc::VERSION}.
+(::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::)
+
+}
+
+  s.add_development_dependency 'rake', '~> 0.8.7'
+  s.add_development_dependency 'rspec', '~> 2.3.0'
+
+  s.rubygems_version   = "1.3.7"
+  s.files            = `git ls-files`.split("\n")
+  s.test_files       = `git ls-files -- {spec,features}/*`.split("\n")
+  s.executables      = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.extra_rdoc_files = ["LICENSE", "README.rdoc", "History.txt"]
+  s.rdoc_options     = ["--charset=UTF-8"]
+  s.require_path     = "lib"
+end

data/lib/active_doc.rb

@@ -0,0 +1,83 @@
+require 'active_doc/described_method'
+module ActiveDoc
+  VERSION = "0.1.0"
+  def self.included(base)
+    base.extend(ClassMethods)
+    base.extend(Dsl)
+    base.class_eval do
+      class << self
+        extend(Dsl)
+      end
+    end
+  end
+
+  class << self
+    def register_description(description)
+      @current_descriptions ||= []
+      @current_descriptions << description
+    end
+    
+    def pop_current_descriptions
+      current_descriptions = @current_descriptions
+      @current_descriptions = nil
+      return current_descriptions
+    end
+    
+    def nested_descriptions
+      before_nesting_descriptions = self.pop_current_descriptions
+      yield
+      after_nesting_descriptions = self.pop_current_descriptions
+      @current_descriptions = before_nesting_descriptions
+      return after_nesting_descriptions
+    end
+
+    def describe(base, method_name, origin)
+      if current_descriptions = pop_current_descriptions
+        @descriptions ||= {}
+        @descriptions[[base, method_name]] = ActiveDoc::DescribedMethod.new(base, method_name, current_descriptions, origin)
+        before_method(base, method_name) do |method, args|
+          args_with_vals = {}
+          method.parameters.each_with_index { |(arg, name), i| args_with_vals[name] = {:val => args[i], :required => (arg != :opt), :defined => (i < args.size)}  }
+          current_descriptions.each { |description| description.validate(args_with_vals) }
+        end
+      end
+    end
+    
+    def documented_method(base, method_name)
+      @descriptions && @descriptions[[base,method_name]]
+    end
+    
+    def documented_methods
+      @descriptions.values
+    end
+
+    def before_method(base, method_name)
+      method = base.instance_method(method_name)
+      base.class_eval do
+        self.send(:define_method, "#{method_name}_with_validation") do |*args|
+          yield method, args
+          self.send("#{method_name}_without_validation", *args)
+        end
+        self.send(:alias_method, :"#{method_name}_without_validation", method_name)
+        self.send(:alias_method, method_name, :"#{method_name}_with_validation")
+      end
+    end
+
+  end
+
+  module Dsl
+  end
+  
+  module ClassMethods
+    def method_added(method_name)
+      ActiveDoc.describe(self, method_name, caller.first)
+    end
+
+    def singleton_method_added(method_name)
+      ActiveDoc.describe(self.singleton_class, method_name, caller.first)
+    end
+  end
+end
+require 'active_doc/descriptions'
+require 'active_doc/rdoc_generator'
+

data/lib/active_doc/described_method.rb

@@ -0,0 +1,38 @@
+module ActiveDoc
+  class DescribedMethod
+    attr_reader :origin_file, :origin_line, :descriptions
+    def initialize(base, method_name, descriptions, origin)
+      @base, @method_name, @descriptions = base, method_name, descriptions
+      @origin_file, @origin_line = origin.split(":")
+      @origin_line = @origin_line.to_i
+    end
+    
+    def to_rdoc
+      rdoc_lines = descriptions.map {|x| x.to_rdoc.lines.map{ |l| "# #{l.chomp}" }}.flatten
+      rdoc_lines.unshift("# ==== Attributes:")
+      return rdoc_lines.join("\n") << "\n"
+    end
+    
+    def write_rdoc(offset)
+      File.open(@origin_file, "r+") do |f|
+        lines = f.readlines
+        rdoc_lines = to_rdoc.lines.to_a
+        rdoc_space_range = rdoc_space_range(offset)
+        lines[rdoc_space_range] = rdoc_lines
+        offset += rdoc_lines.size - rdoc_space_range.to_a.size
+        f.pos = 0
+        lines.each do |line|
+          f.print line
+        end
+        f.truncate(f.pos)
+      end
+      return offset
+    end
+    
+    protected
+    def rdoc_space_range(offset)
+      (descriptions.last.last_line + offset)...(@origin_line + offset-1)
+    end
+    
+  end
+end

data/lib/active_doc/descriptions.rb

@@ -0,0 +1 @@
+require 'active_doc/descriptions/method_argument_description'

data/lib/active_doc/descriptions/method_argument_description.rb

@@ -0,0 +1,426 @@
+module ActiveDoc
+  module Descriptions
+    class MethodArgumentDescription
+      module Dsl
+        # Describes method argument.
+        #
+        # ==== Attributes:
+        # * +name+ :: name of method argument.
+        # * +argument_expectation+ :: expected +Class+, +Regexp+ (or another values see +ArgumentExpectation+ subclasses
+        #                             for more details).
+        # * +options+:
+        #   * +:ref+ :: (/^\\S+#\\S+$/) :: Reference to another method with description of this argument. Suitable when 
+        #                                  passing argument to another method.
+        #   * +:desc+ :: Textual additional description and explanation of argument 
+        #
+        # === Validation
+        # 
+        # When method is described, checking routines are attached to original method. When some argument
+        # does not meet expectations, ArgumentError is raised.
+        #
+        # Argument description is not compulsory, e.g. when you not specify +takes+ for some argument, nothing
+        # happens.
+        # 
+        # ==== Example:
+        #
+        #  takes :contact_name, String, :desc => "Last name of contact person"
+        #  takes :number, /[0-9]{6}/
+        #  def add(contact_name, number)
+        #    ...
+        #  end
+        #
+        # This adds to +add+ methods routines checking, that value of +contact_name+ ia_a? String and 
+        # value of +add+ =~ /[0-9]{6}/.
+        # 
+        # === Nesting:
+        # When describing Hash, it can take a block, that allows additional description of argument 
+        # using the same DSL.
+        #
+        # ==== Example:
+        #
+        #  takes :options, Hash do
+        #    takes :category, String
+        #  end
+        #  def add(number, options)
+        #    ...
+        #  end
+        #
+        # ==== Hash validation:
+        # In current implementation, when describing hash argument with nested description, every expected
+        # key must be mentioned. Reason: preventing from mistakenly sending unexpected options.
+        #
+        # === RDoc generating
+        # 
+        # When generating +RDoc+ comments from +active_doc+, space between last +takes+ description an method definition
+        # is used. *Bear in mind: Everything in this space will be replaced with generated comments*
+        # ==== Example:
+        #
+        #  takes :contact_name, String, :desc => "Last name of contact person"
+        #  takes :number, /[0-9]{6}/
+        #  takes :options, Hash do
+        #    takes :category, String
+        #  end
+        #  # this comment was there before
+        #  def add(contact_name, number, options)
+        #    ...
+        #  end
+        #
+        # After running rake task for RDoc comments, it's changed to:
+        #
+        #  takes :contact_name, String, :desc => "Last name of contact person"
+        #  takes :number, /[0-9]{6}/
+        #  takes :options, Hash do
+        #    takes :category, String
+        #  end
+        #  # ==== Arguments:
+        #  # *+contact_name+ :: (String) :: Last name of contact person
+        #  # *+number+ :: (/[0-9]{6}/) 
+        #  # *+options+ :
+        #  #   * +:category+ :: (String)
+        #  def add(contact_name, number, options)
+        #    ...
+        #  end
+        def takes(name, *args, &block)
+          if args.size > 1 || !args.first.is_a?(Hash)
+            argument_expectation = args.shift || nil
+          else
+            argument_expectation = nil
+          end
+          options = args.pop || {}
+          if ref_string = options[:ref]
+            ActiveDoc.register_description(ActiveDoc::Descriptions::MethodArgumentDescription::Reference.new(name, ref_string, caller.first, options, &block))
+          else
+            ActiveDoc.register_description(ActiveDoc::Descriptions::MethodArgumentDescription.new(name, argument_expectation, caller.first, options, &block))
+          end
+        end
+      end
+
+      class ArgumentExpectation
+        def self.inherited(subclass)
+          @possible_argument_expectations ||= []
+          @possible_argument_expectations << subclass
+        end
+
+        def self.find(argument, options, proc)
+          @possible_argument_expectations.each do |expectation|
+            if suitable_expectation = expectation.from(argument, options, proc)
+              return  suitable_expectation
+            end
+          end
+          return nil
+        end
+
+
+        def fulfilled?(value, args_with_vals)
+          if self.condition?(value, args_with_vals)
+            @failed_value = nil
+            return true
+          else
+            @failed_value = value
+            return false
+          end
+        end
+        
+        # to be inserted after argument description in rdoc
+        def additional_rdoc
+          return nil
+        end
+      end
+      
+      class TypeArgumentExpectation < ArgumentExpectation
+        def initialize(argument)
+          @type = argument
+        end
+
+        def condition?(value, args_with_vals)
+          value.is_a? @type
+        end
+
+        # Expected to...
+        def expectation_fail_to_s
+          "be #{@type.name}, got #{@failed_value.class.name}"
+        end
+
+        def to_rdoc
+          @type.name
+        end
+
+        def self.from(argument, options, proc)
+          if argument.is_a?(Class) && proc.nil?
+            self.new(argument)
+          end
+        end
+      end
+
+      class RegexpArgumentExpectation < ArgumentExpectation
+        def initialize(argument)
+          @regexp = argument
+        end
+
+        def condition?(value, args_with_vals)
+          value =~ @regexp
+        end
+
+        # Expected to...
+        # NOTE: Possible thread-safe problem
+        def expectation_fail_to_s
+          "match #{@regexp}, got '#{@failed_value.inspect}'"
+        end
+
+        def to_rdoc
+          @regexp.inspect.gsub('\\') { '\\\\' }
+        end
+
+        def self.from(argument, options, proc)
+          if argument.is_a? Regexp
+            self.new(argument)
+          end
+        end
+      end
+
+      class ArrayArgumentExpectation < ArgumentExpectation
+        def initialize(argument)
+          @array = argument
+        end
+
+        def condition?(value, args_with_vals)
+          @array.include?(value)
+        end
+
+        # Expected to...
+        # NOTE: Possible thread-safe problem
+        def expectation_fail_to_s
+          "be included in #{@array.inspect}, got #{@failed_value.inspect}"
+        end
+
+        def to_rdoc
+          @array.inspect
+        end
+
+        def self.from(argument, options, proc)
+          if argument.is_a? Array
+            self.new(argument)
+          end
+        end
+      end
+      
+      class ComplexConditionArgumentExpectation < ArgumentExpectation
+        def initialize(argument)
+          @proc = argument
+        end
+
+        def condition?(value, args_with_vals)
+          other_values = args_with_vals.inject({}) { |h, (k, v)| h[k] = v[:val];h }
+          @proc.call(other_values)
+        end
+
+        # Expected to...
+        def expectation_fail_to_s
+          "satisfy given condition, got #{@failed_value.inspect}"
+        end
+
+        def to_rdoc
+          "Complex Condition"
+        end
+
+        def self.from(argument, options, proc)
+          if proc.is_a?(Proc) && proc.arity == 1
+            self.new(proc)
+          end
+        end
+      end
+      
+      class OptionsHashArgumentExpectation < ArgumentExpectation
+        def initialize(argument)
+          @proc = argument
+
+          @hash_descriptions = ActiveDoc.nested_descriptions do
+            Class.new.extend(Dsl).class_exec(&@proc)
+          end
+        end
+
+        def condition?(value, args_with_vals)
+          if @hash_descriptions
+            raise "Only hash is supported for nested argument documentation" unless value.is_a? Hash
+            hash_args_with_vals = value.inject(Hash.new{|h,k| h[k] = {:defined => false}}) do |hash, (key,val)|
+              hash[key] = {:val => val, :defined => true}
+              hash
+            end
+            described_keys   = @hash_descriptions.map do |hash_description|
+              hash_description.validate(hash_args_with_vals)
+            end
+            undescribed_keys = value.keys - described_keys
+            unless undescribed_keys.empty?
+              raise ArgumentError.new("Inconsistent options definition with active doc. Hash was not expected to have arguments '#{undescribed_keys.join(", ")}'")
+            end
+          end
+          return true
+        end
+
+        # Expected to...
+        def expectation_fail_to_s
+          "contain described keys, got #{@failed_value.inspect}"
+        end
+
+        def to_rdoc
+          return "Hash"
+        end
+
+        def additional_rdoc
+          if @hash_descriptions
+            ret = @hash_descriptions.map { |x| "  #{x.to_rdoc(true)}" }.join("\n")
+            ret.insert(0, ":\n")
+            ret
+          end
+        end
+        
+        def last_line
+          @hash_descriptions && @hash_descriptions.last && (@hash_descriptions.last.last_line + 1)
+        end
+
+        def self.from(argument, options, proc)
+          if proc.is_a?(Proc) && proc.arity == 0 && argument == Hash
+            self.new(proc)
+          end
+        end
+      end
+
+      class DuckArgumentExpectation < ArgumentExpectation
+        def initialize(argument)
+          @respond_to = argument
+          @respond_to = [@respond_to] unless @respond_to.is_a? Array
+        end
+
+        def condition?(value, args_with_vals)
+          @failed_quacks = @respond_to.find_all {|quack| not value.respond_to? quack}
+          @failed_quacks.empty?
+        end
+
+        # Expected to...
+        # NOTE: Possible thread-safe problem
+        def expectation_fail_to_s
+          "be respond to #{@respond_to.inspect}, missing #{@failed_quacks.inspect}"
+        end
+
+        def to_rdoc
+          respond_to = @respond_to
+          respond_to = respond_to.first if respond_to.size == 1
+          "respond to #{respond_to.inspect}"
+        end
+
+        def self.from(argument, options, proc)
+          if options[:duck]
+            self.new(options[:duck])
+          end
+        end
+      end
+
+
+      module Traceable
+        def origin_file
+          @origin.split(":").first
+        end
+        
+        def origin_line
+          @origin.split(":")[1].to_i
+        end
+      end
+      
+      attr_reader :name, :origin_file
+      attr_accessor :conjunction
+      include Traceable
+
+      def initialize(name, argument_expectation, origin, options = {}, &block)
+        @name, @origin, @description = name, origin, options[:desc]
+        @argument_expectations = []
+        if found_expectation = ArgumentExpectation.find(argument_expectation, options, block)
+          @argument_expectations << found_expectation
+        elsif block
+          raise "We haven't fount suitable argument expectations for given parameters"
+        end
+        
+        if @argument_expectations.last.respond_to?(:last_line)
+          @last_line = @argument_expectations.last.last_line
+        end
+      end
+
+      def validate(args_with_vals)
+        argument_name = @name
+        if arg_attributes = args_with_vals[@name]
+          if arg_attributes[:required] || arg_attributes[:defined]
+            current_value       = arg_attributes[:val]
+            failed_expectations = @argument_expectations.find_all { |expectation| not expectation.fulfilled?(current_value, args_with_vals) }
+            if !failed_expectations.empty?
+              raise ArgumentError.new("Wrong value for argument '#{argument_name}'. Expected to #{failed_expectations.map { |expectation| expectation.expectation_fail_to_s }.join(",")}")
+            end
+          end
+        else
+          raise ArgumentError.new("Inconsistent method definition with active doc. Method was expected to have argument '#{argument_name}'")
+        end
+        return argument_name
+      end
+
+      def to_rdoc(hash = false)
+        name = hash ? @name.inspect : @name
+        ret = "* +#{name}+"
+        ret << expectations_to_rdoc.to_s
+        ret << desc_to_rdoc.to_s
+        ret << expectations_to_additional_rdoc.to_s
+        return ret
+      end
+
+      def last_line
+        return @last_line || self.origin_line
+      end
+
+      private
+
+      def expectations_to_rdoc
+        expectations_rdocs = @argument_expectations.map { |x| x.to_rdoc }.compact
+        " :: (#{expectations_rdocs.join(", ")})" unless expectations_rdocs.empty?
+      end
+      
+      def expectations_to_additional_rdoc
+        @argument_expectations.map { |argument_expectation| argument_expectation.additional_rdoc }.compact.join
+      end
+
+      def desc_to_rdoc
+        " :: #{@description}" if @description
+      end
+
+      class Reference < MethodArgumentDescription
+        include Traceable
+        def initialize(name, target_description, origin, options)
+          @name = name
+          @klass, @method = target_description.split("#")
+          @klass = Object.const_get(@klass)
+          @method = @method.to_sym
+          @origin = origin
+        end
+        
+        def validate(*args)
+          # we validate only in target method
+          return @name
+        end
+        
+        def to_rdoc(*args)
+            referenced_argument_description.to_rdoc
+        end
+        
+        private
+        
+        def referenced_argument_description
+          if referenced_described_method = ActiveDoc.documented_method(@klass, @method)
+            if referenced_argument_description = referenced_described_method.descriptions.find { |description| description.name == @name }
+              return referenced_argument_description
+            end
+          end
+          raise "Missing referenced argument description '#{@klass.name}##{@method}'"
+        end
+      end
+
+
+    end
+  end
+end
+ActiveDoc::Dsl.send(:include, ActiveDoc::Descriptions::MethodArgumentDescription::Dsl)