== RDoc Method Interface Overloading

RDoc supports the `:call-seq:` directive for defining "virtual"
method interfaces. Given a file +lib/example.rb+ containing a class
with a documented method using the directive:

  class ExampleClass
    # Example method using call-seq directive.
    #
    # :call-seq:
    #   my_method(flazm, saszm) -> nil
    #   my_method(bunny) { |ears| ... } -> true or false
    #
    def my_method(a1,a2=nil,&b)
    end
  end

Running the script through shomen command line interface the signatures list
should have only three entries.

  example = @shomen['ExampleClass#my_method']

  example['signatures'].size  #=> 3

=== Literal Interface

Lets get a closer look at the first signature.

  signature = example['signatures'].first

The first signature should match the literal definition.

  signature['signature']  #=> 'my_method(a1,a2=nil,&b)'

And the arguments should be detailed as expected.

  signature['arguments'][0]['name']      #=> 'a1'
  signature['arguments'][0]['default']   #=> nil

  signature['arguments'][1]['name']      #=> 'a2'
  signature['arguments'][1]['default']   #=> 'nil'

As should the block argument.

  signature['block']['name']  #=> '&b'

=== Virtual Interface

The second and third signatures should conform to those given in
under the `:call-seq:` directive.

Lets get a closer look at the first of these.

  signature = example['signatures'][1]

The signature should match the provided image.

  signature['signature']  #=> 'my_method(flazm, saszm)'

And the arguments should be detailed as expected.

  signature['arguments'][0]['name']      #=> 'flazm'
  signature['arguments'][0]['default']   #=> nil

  signature['arguments'][1]['name']      #=> 'saszm'
  signature['arguments'][1]['default']   #=> nil

This virtual signature does not specify a block so the block argument
should return `nil`.

  signature['block']  #=> nil

Now lets' look at the second virtual signature.

  signature = example['signatures'][2]

The signature should match the provided image.

  signature['signature']  #=> 'my_method(bunny)'

And the arguments should be detailed as expected.

  signature['arguments'][0]['name']      #=> 'bunny'
  signature['arguments'][0]['default']   #=> nil

This virtual signature does specify a block, but not as an argument, but rather
as a representation the call arguments.

  signature['block']['image']  #=> '{ |ears| ... }'

This last signature also give a returns description.

  signature['returns']  #=> 'true or false'