shomen 0.1.0

data/spec/08_rdoc/01_interface_overloading.rdoc

@@ -0,0 +1,94 @@
+== 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'
+

data/spec/09_yard/01_interface_overloading.rdoc

@@ -0,0 +1,93 @@
+== YARD Method Signature Overloading
+
+YARD supports the `@overload` tag for defining "virtual" method interfaces.
+Given a file +lib/example.rb+ containing a class with a documented method
+using the overload tag:
+
+  class ExampleClass
+    # Example method using call-seq directive.
+    #
+    # @overload my_method(flazm, saszm) -> nil
+    # @overload 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 three entries, the literal interface and the two virtual interfaces.
+
+  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'
+

data/spec/applique/shomen.rb

@@ -0,0 +1,26 @@
+require 'shomen/cli'
+require 'stringio'
+
+parser = ENV['parser'] || 'rdoc'
+
+#Before :all do
+  if not File.exist?('.ruby')
+    dotruby = "---\nname: example\n"
+    File.open('.ruby', 'w'){ |f| f << dotruby }
+  end
+#end
+
+When 'Given a file +(((.*?)))+' do |file, text|
+  @file = file
+  FileUtils.mkdir_p(File.dirname(file))
+  File.open(file, 'w'){ |f| f << text }
+end
+
+When 'Running the script through shomen' do
+  output = ''
+  $stdout = StringIO.new(output,'w+')
+  Shomen.cli(parser, '--format', 'yaml', @file)
+  $stdout.close
+  @shomen = YAML.load(output)
+end
+

data/spec/fixture/lib/example.rb

@@ -0,0 +1,52 @@
+# This is an example toplevel class method.
+def self.example_toplevel_method_class_method
+end
+
+# This is an example toplevel instance method.
+def example_toplevel_method
+end
+
+# This is an example module.
+module ExampleModule
+
+  # This is an example constant in a module.
+  EXAMPLE_CONSTANT = "example constant in a module"
+
+  # This is an example class method in a module.
+  def self.example_class_method
+  end
+
+  # This is an example instance method in a module.
+  def example_method
+  end
+
+end
+
+# This is an example class.
+class ExampleClass
+
+  # This is an example constant in a class.
+  EXAMPLE_CONSTANT = "example constant in a class"
+
+  # This is an example class method in a class.
+  def self.example_class_method
+  end
+
+  # This is an example attribute.
+  attr :example_attribute
+
+  # This is an example attribute reader.
+  attr_reader :example_attribute_reader
+
+  # This is an example attribute writer.
+  attr_writer :example_attribute_writer
+
+  # This is an example attribute accessor.
+  attr_accessor :example_attribute_accessor
+
+  # This is an example instance method in a class.
+  def example_method
+  end
+
+end
+

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: shomen
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Thomas Sawyer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-10-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: &16179380 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: *16179380
+- !ruby/object:Gem::Dependency
+  name: detroit
+  requirement: &16178720 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *16178720
+- !ruby/object:Gem::Dependency
+  name: reap
+  requirement: &16178040 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *16178040
+description: Shomen defines a standard API documentaiton format for object-oriented
+  software (Ruby programs in particular) which can be used by documentation interfaces,
+  e.g. Hypervisor, to render API documentation
+email:
+- transfire@gmail.com
+executables:
+- shomen
+extensions: []
+extra_rdoc_files:
+- HISTORY.rdoc
+- README.rdoc
+- NOTES.rdoc
+files:
+- .ruby
+- .yardopts
+- bin/shomen
+- lib/shomen/cli/abstract.rb
+- lib/shomen/cli/rdoc.rb
+- lib/shomen/cli/tomdoc.rb
+- lib/shomen/cli/yard.rb
+- lib/shomen/cli.rb
+- lib/shomen/core_ext/hash.rb
+- lib/shomen/metadata.rb
+- lib/shomen/model/abstract.rb
+- lib/shomen/model/attribute.rb
+- lib/shomen/model/class.rb
+- lib/shomen/model/constant.rb
+- lib/shomen/model/document.rb
+- lib/shomen/model/interface.rb
+- lib/shomen/model/method.rb
+- lib/shomen/model/module.rb
+- lib/shomen/model/script.rb
+- lib/shomen/model.rb
+- lib/shomen/rdoc/extensions.rb
+- lib/shomen/rdoc.rb
+- lib/shomen/server.rb
+- lib/shomen/tomdoc.rb
+- lib/shomen/yard.rb
+- lib/shomen.yml
+- spec/01_metadata.rdoc
+- spec/02_class.rdoc
+- spec/03_module.rdoc
+- spec/04_constant.rdoc
+- spec/05_method.rdoc
+- spec/08_rdoc/01_interface_overloading.rdoc
+- spec/09_yard/01_interface_overloading.rdoc
+- spec/applique/shomen.rb
+- spec/fixture/lib/example.rb
+- HISTORY.rdoc
+- README.rdoc
+- NOTES.rdoc
+homepage: http://rubyworks.github.com/shomen
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.5
+signing_key: 
+specification_version: 3
+summary: Standardized Object-Oriented Documentation Model
+test_files: []