shomen-rdoc 0.1.0

data/lib/shomen-rdoc/rdoc_ext.rb

@@ -0,0 +1,149 @@
+require 'rdoc'
+
+class RDoc::TopLevel
+  #
+  def to_h
+    {
+       :path     => path,
+       :name     => base_name,
+       :fullname => full_name,
+       :rootname => absolute_name,
+       :modified => last_modified,
+       :diagram  => diagram
+    }
+  end
+
+  #
+  #def to_json
+  #  to_h.to_json
+  #end
+end
+
+
+class RDoc::ClassModule
+  #
+  def with_documentation?
+    document_self_or_methods || classes_and_modules.any?{ |c| c.with_documentation? }
+  end
+
+  #
+  def document_self_or_methods
+    document_self || method_list.any?{ |m| m.document_self }
+  end
+
+#  #
+#  def to_h
+#    {
+#      :name       => name,
+#      :fullname   => full_name,
+#      :type       => type,
+#      :path       => path,
+#      :superclass => module? ? nil : superclass
+#    }
+#  end
+#
+#  def to_json
+#    to_h.to_json
+#  end
+end
+
+
+module RDoc::SourceCodeAccess
+
+  #
+  def source_code_raw
+    return '' unless @token_stream
+    src = ""
+    @token_stream.each do |t|
+      next unless t
+      src << t.text
+    end
+    #add_line_numbers(src)
+    src
+  end
+
+  #
+  def source_code_location
+    src = source_code_raw
+    if md = /File (.*?), line (\d+)/.match(src)
+      file = md[1]
+      line = md[2]
+    else
+      file = "(unknown)"
+      line = 0
+    end
+    return file, line
+  end
+
+end
+
+
+class RDoc::AnyMethod
+  include RDoc::SourceCodeAccess
+
+#  # NOTE: dont_rename_initialize isn't used
+#  def to_h
+#    {
+#      :name         => name,
+#      :fullname     => full_name,
+#      :prettyname   => pretty_name,
+#      :path         => path,
+#      :type         => type,
+#      :visibility   => visibility,
+#      :blockparams  => block_params,
+#      :singleton    => singleton,
+#      :text         => text,
+#      :aliases      => aliases,
+#      :aliasfor     => is_alias_for,
+#      :aref         => aref,
+#      :parms        => params,
+#      :callseq      => call_seq
+#      #:paramseq     => param_seq,
+#    }
+#  end
+
+#  #
+#  def to_json
+#    to_h.to_json
+#  end
+end
+
+class RDoc::Attr
+  include RDoc::SourceCodeAccess
+end
+
+=begin
+
+# DEPRECATE ASAP
+require "rdoc/parser/c"
+# New RDoc somehow misses class comemnts.
+# copyied this function from "2.2.2" 
+if ['2.4.2', '2.4.3'].include? RDoc::VERSION
+  class RDoc::Parser::C
+    def find_class_comment(class_name, class_meth)
+      comment = nil
+      if @content =~ %r{((?>/\*.*?\*/\s+))
+                     (static\s+)?void\s+Init_#{class_name}\s*(?:_\(\s*)?\(\s*(?:void\s*)\)}xmi then
+        comment = $1
+      elsif @content =~ %r{Document-(?:class|module):\s#{class_name}\s*?(?:<\s+[:,\w]+)?\n((?>.*?\*/))}m
+        comment = $1
+      else
+        if @content =~ /rb_define_(class|module)/m then
+          class_name = class_name.split("::").last
+          comments = []
+          @content.split(/(\/\*.*?\*\/)\s*?\n/m).each_with_index do |chunk, index|
+            comments[index] = chunk
+            if chunk =~ /rb_define_(class|module).*?"(#{class_name})"/m then
+              comment = comments[index-1]
+              break
+            end
+          end
+        end
+      end
+      class_meth.comment = mangle_comment(comment) if comment
+    end
+  end
+end
+
+=end
+

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'].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
+
+