shomen 0.1.0

data/spec/01_metadata.rdoc

@@ -0,0 +1,24 @@
+== Metadata
+
+All Shomen documents include a `(metadata)` entry which provides information
+about a project in general. Shomen pulls the metadata from one of two sources.
+First, if there is a `.ruby` file in a project it will use the data as given.
+Shomen's metadata format follows the .ruby specification directly. But, if there
+is no `.ruby` file in a project, shomen will look for a .gemspec file and
+convert it (as much as is possible) to the .ruby spec for inclusion.
+
+=== Using a `.ruby` File
+
+TODO
+
+=== Using a `.gemspec` File
+
+TODO
+
+=== Alternate Formats for Other Languages
+
+Of course, if the Shomen documentation standard is used for non-Ruby projects,
+then the metadata specification can vary. While Shomen is designed primarily
+with Ruby i8n mind, it is general enough to serve just about any object-oriented
+programming language.
+

data/spec/02_class.rdoc

@@ -0,0 +1,63 @@
+== Class Documentation
+
+=== Simple Example with a Barren Class
+
+Given a file +lib/example.rb+ containing a minimally documented and
+essentially barren class:
+
+    # This class is documented.
+    class ExampleClass
+    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 three entries.
+
+  @shomen.keys.assert.include?('(metadata)')
+  @shomen.keys.assert.include?('ExampleClass')
+  @shomen.keys.assert.include?('/lib/example.rb')
+
+The `ExampleClass` entry should have a "bang" type of `class`.
+
+  @shomen['ExampleClass']['!']  #=> 'class'
+
+It should have a name of `ExampleClass`.
+
+  @shomen['ExampleClass']['name']  #=> 'ExampleClass'
+
+While the namespace should be an empty string because the class is defined
+at the toplevel.
+
+  @shomen['ExampleClass']['namespace']  #=> ''
+
+The full `path` field will be the same as the name for the same reason.
+
+  @shomen['ExampleClass']['path']  #=> 'ExampleClass'
+
+The `superclass` will be Object.
+
+  @shomen['ExampleClass']['superclass']  #=> 'Object'
+
+The `comment` field will as given in the script.
+
+  @shomen['ExampleClass']['comment']  #=> "This class is documented."
+
+And the `files` field should list only `/lib/example.rb`.
+
+  @shomen['ExampleClass']['files']  #=> ['/lib/example.rb']
+
+Notice that the leading root slash `/` is part of the file name. This refers
+to the root of the project, as opposed to the root of one's file system, and
+makes it easier to lookup files in the index, the the root slash is used to 
+distinguish file names from other entries.
+
+Since out example class is barren the remaining fields will either be 
+missing (i.e. `nil`) or empty collections.
+
+  @shomen['ExampleClass']['constants'].to_a      #=> []
+  @shomen['ExampleClass']['modules'].to_a        #=> []
+  @shomen['ExampleClass']['classes'].to_a        #=> []
+  @shomen['ExampleClass']['methods'].to_a        #=> []
+

data/spec/03_module.rdoc

@@ -0,0 +1,59 @@
+== Module Documentation
+
+=== Simple Example with a Barren Module
+
+Given a file +lib/example.rb+ containing a minimally documented and
+essentially barren class:
+
+    # This module is documented.
+    module ExampleModule
+    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 three entries.
+
+  @shomen.keys.assert.include?('(metadata)')
+  @shomen.keys.assert.include?('ExampleModule')
+  @shomen.keys.assert.include?('/lib/example.rb')
+
+The `ExampleModule` entry should have a "bang" type of `module`.
+
+  @shomen['ExampleModule']['!']  #=> 'module'
+
+It should have a name of `ExampleModule`.
+
+  @shomen['ExampleModule']['name']  #=> 'ExampleModule'
+
+While the namespace should be an empty string because the class is defined
+at the toplevel.
+
+  @shomen['ExampleModule']['namespace']  #=> ''
+
+The full `path` field will be the same as the name for the same reason.
+
+  @shomen['ExampleModule']['path']  #=> 'ExampleModule'
+
+As a module it should not have a `superclass` entry.
+
+  @shomen['ExampleModule'].refute.key?('superclass')
+
+The `comment` field will as given in the script.
+
+  @shomen['ExampleModule']['comment']  #=> "This module is documented."
+
+And the `files` field should list only `lib/example.rb`.
+
+  @shomen['ExampleModule']['files']  #=> ['/lib/example.rb']
+
+Since out example class is barren the remaining fields will either be 
+missing (i.e. `nil`) or empty collections.
+
+  @shomen['ExampleModule']['constants'].to_a      #=> []
+  @shomen['ExampleModule']['modules'].to_a        #=> []
+  @shomen['ExampleModule']['classes'].to_a        #=> []
+  @shomen['ExampleModule']['methods'].to_a        #=> []
+  @shomen['ExampleModule']['class-methods'].to_a  #=> []
+

data/spec/04_constant.rdoc

@@ -0,0 +1,59 @@
+== Constant Documentation
+
+=== Class/Module Constant
+
+Given a file +lib/example.rb+ containing a documented constant in a class
+(or module):
+
+    class ExampleClass
+      # This constant is documented.
+      ExampleConstant = "example"
+    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.size  #=> 4
+
+  @shomen.keys.assert.include?('(metadata)')
+  @shomen.keys.assert.include?('ExampleClass')
+  @shomen.keys.assert.include?('ExampleClass::ExampleConstant')
+  @shomen.keys.assert.include?('/lib/example.rb')
+
+We want to inspect the constant entry itself, so we will assign the entry
+to a variable to ease readability.
+
+  constant = @shomen['ExampleClass::ExampleConstant']
+
+The `ExampleConstant` entry should have a "bang" type of `constant`.
+
+  constant['!']          #=> 'constant'
+
+It should have a name of `ExampleConstant`.
+
+  constant['name']       #=> 'ExampleConstant'
+
+While the namespace should be `ExampleClass`.
+
+  constant['namespace']  #=> 'ExampleClass'
+
+The full `path` field will be the same as the name for the same reason.
+
+  constant['path']       #=> 'ExampleClass::ExampleConstant'
+
+The `comment` field will as given in the script.
+
+  constant['comment']    #=> "This constant is documented."
+
+And the `files` field should list only `lib/example.rb`.
+
+  constant['files']      #=> ['/lib/example.rb']
+
+Lastly, the `value` field should contain the value the literal representation
+of the value to which the constant is set.
+
+  constant['value']      #=> '"example"'
+

data/spec/05_method.rdoc

@@ -0,0 +1,286 @@
+= 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'].first
+
+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
+
+