= Method Documentation

== Instance Method

=== Instance Method without Arguments

Given a file +lib/example.rb+ containing a class with a documented method:

    # This class is documented.
    class ExampleClass
      # This method is documented.
      def example_method
      end
    end

Running the script through shomen command line interface, regardless of which
underlying parser is used, should produce a data structure conforming to the
Shomen standard data format having the following characteristics.

The data structure should have four entries.

    @shomen.keys.assert.include?('(metadata)')
    @shomen.keys.assert.include?('/lib/example.rb')
    @shomen.keys.assert.include?('ExampleClass')
    @shomen.keys.assert.include?('ExampleClass#example_method')

In the following assertions we will repeatedly refer to the `ExampleClass#example_method`
entry, so lets create a short-hnad variable to ease our reeading

    example = @shomen['ExampleClass#example_method']

The example method entry should have a "bang" type of `method`.

    example['!']          #=> 'method'

It should also have a name of `example_method`.

    example['name']       #=> 'example_method'

While the namespace should be the name of the class it is defined within.

    example['namespace']  #=> 'ExampleClass'

The full `path` field will be the class name combined with the method's name.

    example['path']       #=> 'ExampleClass#example_method'

The `comment` field will as given.

    example['comment']    #=> "This method is documented."

The entry will also nThe methods declarations in this case should be the defaults.

    example['declarations'].assert.include?('public')
    example['declarations'].assert.include?('instance')
ot be marked as `singleton`.

    example['singleton']  #=> false

The methods declarations in this case should be the defaults.

    example['declarations'].assert.include?('public')
    example['declarations'].assert.include?('instance')

Technically these declaraitons could be left out becuse they are the defaults,
but our Shomen parser includes them for clarity.

The `file` field should list only `/lib/example.rb`.

    example['file']       #=> '/lib/example.rb'

The `line` field gives the line number on which the method is defined.

    example['line']       #=> 4

The interfaces list will have only one entry which will be essentially empty
since our example method has no arguments.

    example['interfaces'][0]['signature']        #=> 'example_method()'
    example['interfaces'][0]['arguments'].to_a   #=> []
    example['interfaces'][0]['parameters'].to_a  #=> []

Sine the method does not take a block the block value should be `nil`.

    example['interfaces'][0]['block']            #=> nil

=== Instance Method with Arguments

Given a file +lib/example.rb+ containing a class with a documented method which
has arguments:

    # This class is documented.
    class ExampleClass
      # This method is documented.
      def example_method(a=1,o={},&b)
      end
    end

Using RDoc, Running the script through shomen command line interface will not
give us much signature information b/c RDoc has no structured support for 
documenting argument details. But it will still provide some basic
information.

The interfaces list will have only one entry.

    example = @shomen['ExampleClass#example_method']
    example['interfaces'].size #=> 1

Lets get a closer look at this signature.

    signature = example['interfaces'].first

The signature itself should match the literal definition.

    signature['signature']  #=> 'example_method(a=1,o={},&b)'

Each argument should be in the arguments list, but without 
a comment since RDoc does not provide any support for specifying
an argument comment.

    signature['arguments'][0]['name']      #=> 'a'
    signature['arguments'][0]['default']   #=> '1'
    signature['arguments'][0]['comment']   #=> nil

    signature['arguments'][1]['name']      #=> 'o'
    signature['arguments'][1]['default']   #=> '{}'
    signature['arguments'][1]['comment']   #=> nil

RDoc also does not provide support for describing named parameters,
so the list will be `nil` or an empty array.

    signature['parameters'].to_a  #=> []

And the block argument should provide the name of the block argument
but again RDoc does not support a block argument comment.

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


== Class Methods

=== Class Method without Arguments

Given a file +lib/example.rb+ containing a class with a documented class method:

    # This class is documented.
    class ExampleClass
      # This class method is documented.
      def self.example_class_method()
      end
    end

Running the script through shomen command line interface, regardless of which
underlying parser is used, should produce a data structure conforming to the
Shomen standard data format having the following characteristics.

The data structure should have four entries: the metadata entry, an entry
for the source file, an entry for the class and an entry for the class method.

    @shomen.keys.assert.include?('(metadata)')
    @shomen.keys.assert.include?('/lib/example.rb')
    @shomen.keys.assert.include?('ExampleClass')
    @shomen.keys.assert.include?('ExampleClass.example_class_method')

In the following assertions we will repeatedly refer to the `ExampleClass#example_class_method`
entry, so lets create a short-hnad variable to ease our reeading

    example = @shomen['ExampleClass.example_class_method']

The example method entry should have a "bang" type of `class-method`.

    example['!']          #=> 'method'
 
It should also have a name of `example_class_method`.

    example['name']       #=> 'example_class_method'

While the namespace should be the name of the class it is defined within.

    example['namespace']  #=> 'ExampleClass'

The full `path` field will be the class name combined with the method's name.

    example['path']       #=> 'ExampleClass.example_class_method'

The `comment` field will as given.

    example['comment']    #=> "This class method is documented."

The entry will also be marked as `singleton`.

    example['singleton']  #=> true

The methods declarations in this case should contain `class`, since this
is a class method after all.

    example['declarations'].assert.include?('class')

The `file` field should list only `lib/example.rb`.

    example['file']       #=> '/lib/example.rb'

The `line` field gives the line number on which the method is defined.

    example['line']       #=> 4

The interfaces list will have only one entry.

    example['interfaces'].size  #=> 1

Let's make it easier to get a closer look at this signature by assigning
it to a temporary variable.

    sig = example['interfaces'].first

The signature image will be given verbatim.

    sig['signature'].assert == 'example_class_method()'

While arguments and parameters will be empty since our example method has
no arguments.

    sig['arguments'].to_a   #=> []
    sig['parameters'].to_a  #=> []

And since the method does not take a block the block value should be `nil`.

    sig['block']            #=> nil

=== Class Method with Arguments

Given a file +lib/example.rb+ containing a class with a documented method which
has arguments:

    # This class is documented.
    class ExampleClass
      # This class method is documented.
      def self.example_class_method(a=1,o={},&b)
      end
    end

Running the script through shomen command line interface will not
give us much signature information b/c RDoc does not support
documenting argument details and in this case we have not provided
any YARD specific tags for doing so. But it will still provide some
basic information.

The interfaces list will have only one entry.

    example = @shomen['ExampleClass.example_class_method']

    example['interfaces'].size #=> 1

Lets get a closer look at this signature.

    signature = example['interfaces'].last

The signature itself should match the literal definition.

    signature['signature']  #=> 'example_class_method(a=1,o={},&b)'

Each argument should be in the arguments list, but without 
a comment since RDoc does not provide any support for specifying
an argument comment.

    signature['arguments'][0]['name']      #=> 'a'
    signature['arguments'][0]['default']   #=> '1'
    signature['arguments'][0]['comment']   #=> nil

    signature['arguments'][1]['name']      #=> 'o'
    signature['arguments'][1]['default']   #=> '{}'
    signature['arguments'][1]['comment']   #=> nil

RDoc also does not provide support for describing named parameters,
so the list will be `nil` or an empty array.

    signature['parameters'].to_a   #=> []

And the block argument should provide the name of the block argument
but again RDoc does not support a block argument comment.

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