inch 0.4.6 → 0.4.7

data/test/unit/cli/yardopts_helper_test.rb

@@ -1,4 +1,4 @@
-require File.expand_path(File.dirname(__FILE__) + '/../../test_helper')
+require File.expand_path(File.dirname(__FILE__) + "/../../test_helper")
 
 describe ::Inch::CLI::YardoptsHelper do
   before do
@@ -9,7 +9,7 @@ describe ::Inch::CLI::YardoptsHelper do
 
   it "should run without args" do
     out, err = capture_io do
-      @command.run()
+      @command.run
     end
     refute out.empty?, "there should be some output"
     assert err.empty?, "there should be no errors"
@@ -56,7 +56,8 @@ describe ::Inch::CLI::YardoptsHelper do
     end
     refute out.empty?, "there should be some output"
     assert_match /\bUsage\b.+list/, out
-    #assert_match /\b\-\-\[no\-\]yardopts\b/, out, "--[no-]yardopts should be mentioned"
+    # assert_match /\b\-\-\[no\-\]yardopts\b/, out,
+    #              "--[no-]yardopts should be mentioned"
     assert err.empty?, "there should be no errors"
   end
 end

data/test/unit/code_object/converter_test.rb

@@ -1,4 +1,4 @@
-require File.expand_path(File.dirname(__FILE__) + '/../../test_helper')
+require File.expand_path(File.dirname(__FILE__) + "/../../test_helper")
 
 describe ::Inch::CodeObject::Converter do
   class MockObject

data/test/unit/code_object/provider/yard/docstring_test.rb

@@ -1,4 +1,4 @@
-require File.expand_path(File.dirname(__FILE__) + '/../../../../test_helper')
+require File.expand_path(File.dirname(__FILE__) + "/../../../../test_helper")
 
 describe ::Inch::CodeObject::Provider::YARD::Docstring do
   let(:described_class) { ::Inch::CodeObject::Provider::YARD::Docstring }
@@ -7,9 +7,8 @@ describe ::Inch::CodeObject::Provider::YARD::Docstring do
   # loose TomDoc compatibility
   #
 
-
   it "should notice things in tomdoc style docs" do
-text = <<-DOC
+    text = <<-DOC
 Internal: Detects the Language of the blob.
 
 param1 - String filename
@@ -19,7 +18,7 @@ param2 - String blob data. A block also maybe passed in for lazy
 param3 - Optional String mode (defaults to nil)
 
 Returns Language or nil.
-DOC
+    DOC
     docstring = described_class.new(text)
     assert docstring.describes_internal_api?
     assert docstring.mentions_parameter?(:param1)
@@ -34,7 +33,7 @@ DOC
   end
 
   it "should notice things in tomdoc style docs 2" do
-text = <<-DOC
+    text = <<-DOC
 Public: Look up Language by one of its aliases.
 
 param1 - A String alias of the Language
@@ -45,7 +44,7 @@ Examples
   # => #<Language name="C++">
 
 Returns the Lexer or nil if none was found.
-DOC
+    DOC
     docstring = described_class.new(text)
     assert docstring.mentions_parameter?(:param1)
     assert docstring.describes_parameter?(:param1)
@@ -56,8 +55,33 @@ DOC
     assert docstring.describes_return?
   end
 
+  it "should notice multi-line returns in tomdoc style docs" do
+    text = <<-DOC
+Public: Look up Language by one of its aliases.
+
+Returns the Lexer or nil
+  if none was found.
+    DOC
+    docstring = described_class.new(text)
+    assert docstring.mentions_return?
+    assert docstring.describes_return?
+  end
+
+  it "should notice multi-line returns in tomdoc style docs 2" do
+    text = <<-DOC
+Public: Look up Language by one of its aliases.
+
+Returns the Lexer or nil
+  if none
+  was found.
+    DOC
+    docstring = described_class.new(text)
+    assert docstring.mentions_return?
+    assert docstring.describes_return?
+  end
+
   it "should notice things in tomdoc style docs 3" do
-text = <<-DOC
+    text = <<-DOC
 Public: Look up Language by one of its aliases.
 
 param1 - A String alias of the Language
@@ -68,7 +92,7 @@ Examples
   # => #<Language name="C++">
 
 Returns the Lexer or nil if none was found.
-DOC
+    DOC
     docstring = described_class.new(text)
     assert docstring.mentions_parameter?(:param1)
     assert docstring.describes_parameter?(:param1)
@@ -79,42 +103,79 @@ DOC
     assert docstring.describes_return?
   end
 
+  it "should understand 'Returns nil.'" do
+    text = <<-DOC
+[...]
+Returns nil.
+    DOC
+    docstring = described_class.new(text)
+    assert docstring.describes_return?
+  end
+
+  it "should understand 'Returns nil.' without fullstop and in lowercase" do
+    text = <<-DOC
+[...]
+returns nil
+    DOC
+    docstring = described_class.new(text)
+    assert docstring.describes_return?
+  end
+
+  it "should understand 'Returns nothing.'" do
+    text = <<-DOC
+[...]
+Returns nothing.
+    DOC
+    docstring = described_class.new(text)
+    assert docstring.describes_return?
+  end
+
+  it "should understand 'Returns nothing.' without fullstop and in lowercase" do
+    text = <<-DOC
+[...]
+returns nothing
+    DOC
+    docstring = described_class.new(text)
+    assert docstring.describes_return?
+  end
+
+  it "should understand 'Returns ...' with a visibility modifier in front of it" do
+    text = "Public: Returns the Integer color."
+    docstring = described_class.new(text)
+    assert docstring.mentions_return?
+    assert docstring.describes_return?
+  end
 
   #
   # PARAMETER MENTIONS
   #
 
-
   it "should work 2" do
-text = <<-DOC
+    text = <<-DOC
 Just because format_html is mentioned here, does not mean
 the first parameter is mentioned.
-DOC
+    DOC
     docstring = described_class.new(text)
     refute docstring.mentions_parameter?(:format)
     refute docstring.contains_code_example?
   end
 
-
-  it "should work 2" do
-text = <<-DOC
+  it "should work 2 if correct" do
+    text = <<-DOC
 Just because format is mentioned here, does not mean
 the first parameter is meant.
-DOC
+    DOC
     docstring = described_class.new(text)
     refute docstring.mentions_parameter?(:format)
     refute docstring.contains_code_example?
   end
 
-
-
   #
   # CODE EXAMPLES
   #
 
-
   it "should work 3" do
-text = <<-DOC
+    text = <<-DOC
 An example of a method using RDoc rather than YARD.
 
 == Parameters:
@@ -123,13 +184,13 @@ param1::
 
 == Returns:
 A string in the specified format.
-DOC
+    DOC
     docstring = described_class.new(text)
     refute docstring.contains_code_example?
   end
 
   it "should work with code example" do
-text = <<-DOC
+    text = <<-DOC
 Another example.
 
   method_with_code_example() # => some value
@@ -138,7 +199,7 @@ Params:
 +param1+:: param1 line string to be executed by the system
 +param2+:: +Proc+ object that takes a pipe object as first and only param (may be nil)
 +param3+:: +Proc+ object that takes a pipe object as first and only param (may be nil)
-DOC
+    DOC
     docstring = described_class.new(text)
     assert docstring.contains_code_example?
     assert docstring.mentions_parameter?(:param1)
@@ -149,21 +210,37 @@ DOC
     assert docstring.describes_parameter?(:param3)
   end
 
+  it "should recognize several parameter notations" do
+    text = <<-DOC
+Params:
++param1<String>+:: param1 line string to be executed by the system
++param2<String,nil>+:: +Proc+ object that takes a pipe object as first and only param (may be nil)
++param3<String|Class>+:: +Proc+ object that takes a pipe object as first and only param (may be nil)
+    DOC
+    docstring = described_class.new(text)
+    assert docstring.mentions_parameter?(:param1), "should mention param1"
+    assert docstring.mentions_parameter?(:param2), "should mention param2"
+    assert docstring.mentions_parameter?(:param3), "should mention param3"
+    assert docstring.describes_parameter?(:param1), "should describe param1"
+    assert docstring.describes_parameter?(:param2), "should describe param2"
+    assert docstring.describes_parameter?(:param3), "should describe param3"
+  end
+
   it "should work with code example 2" do
-text = <<-DOC
+    text = <<-DOC
 Just because format_html is mentioned here, does not mean
 the first parameter is mentioned.
 
   method_with_code_example() # => some value
   method_with_missing_param_doc(param1, param2, param3)
-DOC
+    DOC
     docstring = described_class.new(text)
     assert docstring.contains_code_example?
     assert_equal 1, docstring.code_examples.size
   end
 
   it "should work with code example 3" do
-text = <<-DOC
+    text = <<-DOC
 An example of a method using RDoc rather than YARD.
 
   method_with_code_example() # => some value
@@ -174,7 +251,7 @@ param1::
 
 == Returns:
 A string in the specified format.
-DOC
+    DOC
     docstring = described_class.new(text)
     assert docstring.contains_code_example?
     assert_equal 1, docstring.code_examples.size
@@ -183,7 +260,7 @@ DOC
   end
 
   it "should work with multiple code examples" do
-text = <<-DOC
+    text = <<-DOC
 An example of a method using RDoc rather than YARD.
 
   method_with_code_example() # => some value
@@ -199,7 +276,7 @@ param1::
 
 == Returns:
 A string in the specified format.
-DOC
+    DOC
     docstring = described_class.new(text)
     assert docstring.contains_code_example?
     assert_equal 2, docstring.code_examples.size

data/test/unit/code_object/provider/yard/nodoc_helper_test.rb

@@ -1,4 +1,4 @@
-require File.expand_path(File.dirname(__FILE__) + '/../../../../test_helper')
+require File.expand_path(File.dirname(__FILE__) + "/../../../../test_helper")
 
 describe ::Inch::CodeObject::Provider::YARD::NodocHelper do
   before do
@@ -17,9 +17,9 @@ describe ::Inch::CodeObject::Provider::YARD::NodocHelper do
       "Foo::HiddenClass::EvenMoreHiddenClass",
       "Foo::HiddenClass::EvenMoreHiddenClass#method_with_implicit_nodoc",
       "Foo::HiddenClassViaTag",
-      "Foo::HiddenClassViaTag#some_value",
+      "Foo::HiddenClassViaTag#some_value"
     ].each do |query|
-      m = @objects.detect { |o| o.fullname == query }
+      m = @objects.find { |o| o.fullname == query }
       assert m.nodoc?, "nodoc? should return true for #{query}"
     end
   end
@@ -30,9 +30,9 @@ describe ::Inch::CodeObject::Provider::YARD::NodocHelper do
       "Foo::Qux::Quux::PUBLIC_VALUE",
       "Foo::Qux::DOCCED_VALUE",
       "Foo::HiddenClass::EvenMoreHiddenClass::SuddenlyVisibleClass",
-      "Foo::HiddenClass::EvenMoreHiddenClass::SuddenlyVisibleClass#method_with_implicit_doc",
+      "Foo::HiddenClass::EvenMoreHiddenClass::SuddenlyVisibleClass#method_with_implicit_doc"
     ].each do |query|
-      m = @objects.detect { |o| o.fullname == query }
+      m = @objects.find { |o| o.fullname == query }
       refute m.nodoc?, "nodoc? should return false for #{query}"
     end
   end

data/test/unit/code_object/provider/yard/object/method_object_test.rb

@@ -1,14 +1,17 @@
-require File.expand_path(File.dirname(__FILE__) + '/../../../../../test_helper')
+require File.expand_path(File.dirname(__FILE__) + "/../../../../../test_helper")
 
 describe ::Inch::CodeObject::Provider::YARD::Parser do
   before do
     @config = Inch::Config.codebase
-    @parser = ::Inch::CodeObject::Provider::YARD::Parser.parse(fixture_path(:simple), @config)
+    @parser = ::Inch::CodeObject::Provider::YARD::Parser.parse(
+      fixture_path(:simple), @config)
     @objects = @parser.objects
   end
 
   it "should work for Overloading#params_also_in_overloads" do
-    m = @objects.detect { |o| o.fullname == 'Overloading#params_also_in_overloads' }
+    m = @objects.find do |o|
+      o.fullname == "Overloading#params_also_in_overloads"
+    end
 
     assert m.has_code_example?
 
@@ -16,7 +19,8 @@ describe ::Inch::CodeObject::Provider::YARD::Parser do
     assert_equal 2, m.parameters.size # at this moment, this counts all parameters in all overloaded signatures
 
     signature = m.signatures[0]
-    assert_equal "params_also_in_overloads(user_options = {})", signature.signature
+    assert_equal "params_also_in_overloads(user_options = {})",
+                 signature.signature
     assert_equal 1, signature.parameters.size
     refute signature.parameter(:user_options).nil?
     assert signature.has_code_example?
@@ -24,7 +28,8 @@ describe ::Inch::CodeObject::Provider::YARD::Parser do
 
     signature = m.signatures[1]
     assert_equal "params_also_in_overloads()", signature.signature
-    assert signature.parameters.empty?, "Should have been empty: #{signature.parameters.inspect}"
+    assert signature.parameters.empty?,
+           "Should have been empty: #{signature.parameters.inspect}"
     assert signature.has_code_example?
     refute signature.has_doc?
 
@@ -37,7 +42,9 @@ describe ::Inch::CodeObject::Provider::YARD::Parser do
   end
 
   it "should work for Overloading#params_only_in_overloads" do
-    m = @objects.detect { |o| o.fullname == 'Overloading#params_only_in_overloads' }
+    m = @objects.find do |o|
+      o.fullname == "Overloading#params_only_in_overloads"
+    end
 
     assert m.has_code_example?
 
@@ -46,7 +53,8 @@ describe ::Inch::CodeObject::Provider::YARD::Parser do
 
     signature = m.signatures[0]
     assert_equal "params_only_in_overloads()", signature.signature
-    assert signature.parameters.empty?, "Should have been empty: #{signature.parameters.inspect}"
+    assert signature.parameters.empty?,
+           "Should have been empty: #{signature.parameters.inspect}"
     assert signature.has_code_example?
     refute signature.has_doc?
 
@@ -62,17 +70,19 @@ describe ::Inch::CodeObject::Provider::YARD::Parser do
     assert_equal 1, signature.parameters.size
     refute signature.parameter(:user_options).nil?
     assert signature.has_code_example?
-    #assert signature.has_doc?
+    # assert signature.has_doc?
   end
 
   it "should work" do
-    m = @objects.detect { |o| o.fullname == 'Foo::Bar#method_with_unstructured_doc' }
+    m = @objects.find do |o|
+      o.fullname == "Foo::Bar#method_with_unstructured_doc"
+    end
     assert_equal 1, m.signatures.size
     assert_equal 1, m.parameters.size
   end
 
   it "should work 2" do
-    m = @objects.detect { |o| o.fullname == 'Foo#method_with_splat_parameter' }
+    m = @objects.find { |o| o.fullname == "Foo#method_with_splat_parameter" }
     assert_equal 1, m.signatures.size
     assert_equal 1, m.parameters.size
   end

data/test/unit/code_object/provider/yard_test.rb

@@ -1,4 +1,4 @@
-require File.expand_path(File.dirname(__FILE__) + '/../../../test_helper')
+require File.expand_path(File.dirname(__FILE__) + "/../../../test_helper")
 
 describe ::Inch::CodeObject::Provider::YARD do
   let(:described_class) { ::Inch::CodeObject::Provider::YARD }
@@ -12,14 +12,14 @@ describe ::Inch::CodeObject::Provider::YARD do
     fullname = "Foo#b"
 
     provider1 = described_class.parse(fixture_path(:diff1))
-    object1 = provider1.objects.detect { |o| o.fullname == fullname }
+    object1 = provider1.objects.find { |o| o.fullname == fullname }
 
     provider2 = described_class.parse(fixture_path(:diff2))
-    object2 = provider2.objects.detect { |o| o.fullname == fullname }
+    object2 = provider2.objects.find { |o| o.fullname == fullname }
 
     refute object1.nil?
     refute object2.nil?
     assert object1.object_id != object2.object_id
   end
 
-end
+end

data/test/unit/code_object/provider_test.rb

@@ -1,4 +1,4 @@
-require File.expand_path(File.dirname(__FILE__) + '/../../test_helper')
+require File.expand_path(File.dirname(__FILE__) + "/../../test_helper")
 
 describe ::Inch::CodeObject::Provider do
   it "should parse all objects" do

data/test/unit/code_object/proxy/method_object_test.rb

@@ -1,4 +1,4 @@
-require File.expand_path(File.dirname(__FILE__) + '/../../../test_helper')
+require File.expand_path(File.dirname(__FILE__) + "/../../../test_helper")
 
 describe ::Inch::CodeObject::Proxy::MethodObject do
   before do
@@ -6,47 +6,55 @@ describe ::Inch::CodeObject::Proxy::MethodObject do
     @objects = @codebase.objects
   end
 
-  def test_transitive_tags_dont_matter
-    m = @objects.find("InchTest::Deprecated::ClassMethods")
-    assert_equal 0, m.score
-    assert m.undocumented?
-  end
+  describe "Scores" do
+    #
+    it "should not count tags that are transitive" do
+      m = @objects.find("InchTest::Deprecated::ClassMethods")
+      assert_equal 0, m.score
+      assert m.undocumented?
+    end
 
-  def test_raising_method_with_comment
-    m = @objects.find("InchTest#raising_method_with_comment")
-    assert m.score > 0
-    refute m.undocumented?
-  end
+    it "counts a @raise tag" do
+      m = @objects.find("InchTest#raising_method_with_comment")
+      assert m.score > 0
+      refute m.undocumented?
+    end
 
-  def test_raising_method
-    m = @objects.find("InchTest#raising_method")
-    assert_equal 0, m.score
-    assert m.undocumented?
-  end
+    it "should not count a call to `raise`" do
+      m = @objects.find("InchTest#raising_method")
+      assert_equal 0, m.score
+      assert m.undocumented?
+    end
 
-  def test_yielding_method
-    m = @objects.find("InchTest#yielding_method")
-    assert_equal 0, m.score
-    assert m.undocumented?
+    it "should not count a call to `yield`" do
+      m = @objects.find("InchTest#yielding_method")
+      assert_equal 0, m.score
+      assert m.undocumented?
+    end
   end
 
-  def test_tagged_as_private
-    %w( InchTest#method_with_private_tag
-        InchTest#private_method_with_tomdoc).each do |fullname|
-      m = @objects.find(fullname)
-      assert m.tagged_as_private?
+  describe "Taggings" do
+    #
+    it "should recognize forms of @private-tags" do
+      %w( InchTest#method_with_private_tag
+          InchTest#private_method_with_tomdoc).each do |fullname|
+        m = @objects.find(fullname)
+        assert m.tagged_as_private?
+      end
     end
-  end
 
-  def test_tagged_as_internal_api
-    %w( InchTest#private_api_with_yard
-        InchTest#internal_api_with_tomdoc).each do |fullname|
-      m = @objects.find(fullname)
-      assert m.tagged_as_internal_api?
+    it "should recognize forms of internal-tags" do
+      # @api private in YARD
+      # Internal: in TomDoc
+      %w( InchTest#private_api_with_yard
+          InchTest#internal_api_with_tomdoc).each do |fullname|
+        m = @objects.find(fullname)
+        assert m.tagged_as_internal_api?
+      end
     end
   end
 
-  def test_method_without_doc
+  it "should recognize undocumented methods without parameters" do
     m = @objects.find("Foo::Bar#method_without_doc")
     refute m.has_doc?
     refute m.has_parameters?
@@ -56,7 +64,7 @@ describe ::Inch::CodeObject::Proxy::MethodObject do
     assert_equal 0, m.score
   end
 
-  def test_method_with_missing_param_doc
+  it "should recognize missing parameter documentation" do
     m = @objects.find("Foo::Bar#method_with_missing_param_doc")
     assert m.has_doc?
     assert m.has_parameters?
@@ -67,287 +75,383 @@ describe ::Inch::CodeObject::Proxy::MethodObject do
     assert p.mentioned?
     p = m.parameter(:param2)
     assert p.mentioned?
+
+    # not mentioned
     p = m.parameter(:param3)
     refute p.mentioned?
 
     assert m.score
   end
 
-  def test_method_with_wrong_doc
-    m = @objects.find("Foo::Bar#method_with_wrong_doc")
-    assert m.has_doc?
-    assert m.has_parameters?
-    assert m.return_mentioned?
+  describe "Documentation Styles" do
+    #
+    it "should handle YARD when no additional docstring is given" do
+      m = @objects.find("Foo::Bar#method_without_docstring")
+      refute m.has_doc?
+      assert m.has_parameters?
+      assert m.return_mentioned?
 
-    assert_equal 4, m.parameters.size
-    p = m.parameter(:param1)
-    assert p.mentioned?         # mentioned in docs, correctly
-    refute p.wrongly_mentioned?
-    p = m.parameter(:param2)
-    refute p.mentioned?
-    refute p.wrongly_mentioned? # not mentioned in docs at all
-    p = m.parameter(:param3)
-    refute p.mentioned?
-    refute p.wrongly_mentioned? # not mentioned in docs at all
-    p = m.parameter(:param4)
-    assert p.mentioned?
-    assert p.wrongly_mentioned? # mentioned in docs, but not present
+      assert m.score
+    end
 
-    assert m.score
-  end
+    it "should handle YARD when only @return is given" do
+      m = @objects.find("Foo::Bar#method_without_params_or_docstring")
+      refute m.has_doc?
+      refute m.has_parameters?
+      assert m.return_mentioned?
 
-  def test_method_with_full_doc
-    m = @objects.find("Foo::Bar#method_with_full_doc")
-    assert m.has_doc?
-    assert m.has_parameters?
-    assert m.return_mentioned?
+      assert m.score
+    end
+
+    it "should handle RDoc" do
+      m = @objects.find("Foo::Bar#method_with_rdoc_doc")
+      assert m.has_doc?
+      assert m.has_parameters?
+      p = m.parameter(:param1)
+      assert p.mentioned?         # mentioned in docs, correctly
+      refute m.return_mentioned?
 
-    assert_equal 2, m.parameters.size
-    m.parameters.each do |param|
-      assert param.mentioned?
-      assert param.typed?
-      assert param.described?
-      refute param.wrongly_mentioned?
+      assert m.score
     end
 
-    assert_equal 100, m.score
-  end
+    it "should handle other RDoc styles" do
+      m = @objects.find("Foo::Bar#method_with_other_rdoc_doc")
+      assert m.has_doc?
+      assert m.has_parameters?
+      p = m.parameter(:param1)
+      assert p.mentioned?         # mentioned in docs, correctly
+      p = m.parameter(:param2)
+      assert p.mentioned?         # mentioned in docs, correctly
+      p = m.parameter(:param3)
+      assert p.mentioned?         # mentioned in docs, correctly
+      refute m.return_mentioned?
+
+      assert m.score
+    end
 
-  def test_method_without_params_or_return_type
-    m = @objects.find("Foo::Bar#method_without_params_or_return_type")
-    assert m.has_doc?
-    refute m.has_parameters?
-    refute m.return_mentioned?
+    it "should handle yet other RDoc styles" do
+      m = @objects.find("Foo::Bar#method_with_yet_another_rdoc_doc")
+      assert m.has_doc?
+      assert m.has_parameters?
+      p = m.parameter(:param1)
+      assert p.mentioned?         # mentioned in docs, correctly
+      p = m.parameter(:param2)
+      assert p.mentioned?         # mentioned in docs, correctly
 
-    assert m.score
-  end
+      assert m.score
+    end
 
-  def test_method_without_docstring
-    m = @objects.find("Foo::Bar#method_without_docstring")
-    refute m.has_doc?
-    assert m.has_parameters?
-    assert m.return_mentioned?
+    it "should handle unstructured doc styles" do
+      m = @objects.find("Foo::Bar#method_with_unstructured_doc")
+      assert m.has_doc?
+      assert m.has_parameters?
+      p = m.parameter(:param1)
+      assert p.mentioned?         # mentioned in docs, correctly
+      refute m.return_mentioned?
 
-    assert m.score
-  end
+      assert m.score
+    end
 
-  def test_method_without_params_or_docstring
-    m = @objects.find("Foo::Bar#method_without_params_or_docstring")
-    refute m.has_doc?
-    refute m.has_parameters?
-    assert m.return_mentioned?
+    it "should handle unstructured doc styles with an undocumented param" do
+      m = @objects.find("Foo::Bar#method_with_unstructured_doc_missing_params")
+      assert m.has_doc?
+      assert m.has_parameters?
+      p = m.parameter(:format)
+      refute p.mentioned?         # mentioned in docs, correctly
+      refute m.return_mentioned?
 
-    assert m.score
-  end
+      assert m.score
+    end
 
-  def test_method_with_rdoc_doc
-    m = @objects.find("Foo::Bar#method_with_rdoc_doc")
-    assert m.has_doc?
-    assert m.has_parameters?
-    p = m.parameter(:param1)
-    assert p.mentioned?         # mentioned in docs, correctly
-    refute m.return_mentioned?
+    it "should handle methods (without parameters) that have only a docstring (text comment)" do
+      m = @objects.find("Foo::Bar#method_without_params_or_return_type")
+      assert m.has_doc?
+      refute m.has_parameters?
+      refute m.return_mentioned?
 
-    assert m.score
+      assert m.score
+    end
   end
 
-  def test_method_with_other_rdoc_doc
-    m = @objects.find("Foo::Bar#method_with_other_rdoc_doc")
-    assert m.has_doc?
-    assert m.has_parameters?
-    p = m.parameter(:param1)
-    assert p.mentioned?         # mentioned in docs, correctly
-    p = m.parameter(:param2)
-    assert p.mentioned?         # mentioned in docs, correctly
-    p = m.parameter(:param3)
-    assert p.mentioned?         # mentioned in docs, correctly
-    refute m.return_mentioned?
+  describe "Getter/Setter Handling" do
 
-    assert m.score
-  end
+    it "should recognize a getter method" do
+      m = @objects.find("InchTest#getter")
+      assert m.getter?, "should be a getter"
+      refute m.setter?
+      refute m.has_doc?
+      assert_equal 0, m.score
+    end
 
-  def test_method_with_unstructured_doc
-    m = @objects.find("Foo::Bar#method_with_unstructured_doc")
-    assert m.has_doc?
-    assert m.has_parameters?
-    p = m.parameter(:param1)
-    assert p.mentioned?         # mentioned in docs, correctly
-    refute m.return_mentioned?
+    it "should recognize a setter method" do
+      m = @objects.find("InchTest#attr_setter=")
+      refute m.getter?
+      assert m.setter?, "should be a setter"
+      refute m.has_doc?
+      assert_equal 0, m.score
+    end
 
-    assert m.score
-  end
+    it "should recognize a manually defined setter method" do
+      m = @objects.find("InchTest#manual_setter=")
+      refute m.getter?
+      assert m.setter?, "should be a setter"
+      refute m.has_doc?
+      assert_equal 0, m.score
+    end
 
-  def test_method_with_unstructured_doc_missing_params
-    m = @objects.find("Foo::Bar#method_with_unstructured_doc_missing_params")
-    assert m.has_doc?
-    assert m.has_parameters?
-    p = m.parameter(:format)
-    refute p.mentioned?         # mentioned in docs, correctly
-    refute m.return_mentioned?
+    it "should recognize a getter in a manually defined getter/setter pair" do
+      m = @objects.find("InchTest#manual_getset")
+      assert m.getter?, "should be a getter"
+      refute m.setter?
+      refute m.has_doc?
+      assert_equal 0, m.score
+    end
 
-    assert m.score
-  end
+    it "should recognize a setter in a manually defined getter/setter pair" do
+      m = @objects.find("InchTest#manual_getset=")
+      refute m.getter?
+      assert m.setter?, "should be a setter"
+      refute m.has_doc?
+      assert_equal 0, m.score
+    end
 
-  def test_question_mark_method
-    m = @objects.find("InchTest#question_mark_method?")
-    refute m.has_doc?
-    refute m.has_parameters?
+    it "should recognize a getter in a getter/setter pair defined via attr_accessor" do
+      m = @objects.find("InchTest#attr_getset")
+      assert m.getter?, "should be a getter"
+      refute m.setter?
+      refute m.has_doc?
+      assert_equal 0, m.score
+    end
 
-    assert_equal 0, m.score
-  end
+    it "should recognize a setter in a getter/setter pair defined via attr_accessor" do
+      m = @objects.find("InchTest#attr_getset=")
+      refute m.getter?
+      assert m.setter?, "should be a setter"
+      refute m.has_doc?
+      assert_equal 0, m.score
+    end
 
-  def test_question_mark_method_with_description
-    m = @objects.find("InchTest#question_mark_method_with_description?")
-    refute m.has_doc?
-    refute m.has_parameters?
+    it "should recognize a getter in a getter/setter pair defined via Struct" do
+      m = @objects.find("InchTest::StructGetSet#struct_getset")
+      assert m.getter?, "should be a getter"
+      refute m.setter?
+      refute m.has_doc?
+      assert_equal 0, m.score
+    end
 
-    assert m.score > 0
-    assert m.score >= 50 # TODO: don't use magic numbers
-  end
+    it "should recognize a setter in a getter/setter pair defined via Struct" do
+      m = @objects.find("InchTest::StructGetSet#struct_getset=")
+      refute m.getter?
+      assert m.setter?, "should be a setter"
+      refute m.has_doc?
+      assert_equal 0, m.score
+    end
 
-  def test_method_with_description_and_parameters
-    m = @objects.find("InchTest#method_with_description_and_parameters?")
-    refute m.has_doc?
-    assert m.has_parameters?
+    it "should recognize docs on a getter in a getter/setter pair defined via attr_accessor" do
+      m = @objects.find("Attributes#username")
+      refute_equal 0, m.score
+      refute m.undocumented?
+    end
 
-    assert m.score > 0
-  end
+    it "should recognize docs on a setter in a getter/setter pair defined via attr_accessor" do
+      m = @objects.find("Attributes#username=")
+      refute_equal 0, m.score
+      refute m.undocumented?
+    end
 
-  def test_depth
-    m = @objects.find("#root_method")
-    assert_equal 1, m.depth
-    m = @objects.find("InchTest#getter")
-    assert_equal 2, m.depth
-    m = @objects.find("Foo::Bar#method_without_doc")
-    assert_equal 3, m.depth
-  end
+    it "should recognize splat parameter notation" do
+      # it should assign the same score whether the parameter is
+      # described with or without the splat (*) operator
+      m1 = @objects.find("Foo#method_with_splat_parameter")
+      m2 = @objects.find("Foo#method_with_splat_parameter2")
+      assert_equal 1, m1.parameters.size
+      assert_equal 1, m2.parameters.size
+      assert_equal m1.score, m2.score
+    end
 
-  def test_getter
-    m = @objects.find("InchTest#getter")
-    assert m.getter?, "should be a getter"
-    refute m.setter?
-    refute m.has_doc?
-    assert_equal 0, m.score
+    it "should recognize alias methods and aliased methods" do
+      m1 = @objects.find("InchTest#_aliased_method")
+      m2 = @objects.find("InchTest#_alias_method")
+      assert_equal m1.score, m2.score
+    end
   end
 
-  def test_setter
-    m = @objects.find("InchTest#attr_setter=")
-    refute m.getter?
-    assert m.setter?, "should be a setter"
-    refute m.has_doc?
-    assert_equal 0, m.score
-  end
+  describe "YARDs @!attribute directive on a class" do
+    #
+    it "should work as a reader" do
+      m = @objects.find("Attributes#email")
+      refute_equal 0, m.score
+      refute m.undocumented?
+    end
 
-  def test_setter2
-    m = @objects.find("InchTest#manual_setter=")
-    refute m.getter?
-    assert m.setter?, "should be a setter"
-    refute m.has_doc?
-    assert_equal 0, m.score
+    it "should work as a writer" do
+      m = @objects.find("Attributes#email=")
+      refute_equal 0, m.score
+      # refute m.undocumented?
+      # NOTE: this is undocumented since there is no original_docstring
+    end
   end
 
-  def test_manual_getset
-    m = @objects.find("InchTest#manual_getset")
-    assert m.getter?, "should be a getter"
-    refute m.setter?
-    refute m.has_doc?
-    assert_equal 0, m.score
-  end
+  describe "YARDs @overload tag on methods" do
+    #
+    it "should work with basic overloading" do
+      list = []
+      list << @objects.find("Overloading#rgb")
+      list << @objects.find("Overloading#rgba")
+      list << @objects.find("Overloading#change_color")
+      list << @objects.find("Overloading#mix")
+      list << @objects.find("Overloading#hooks")
+      list << @objects.find("Overloading#identifiers")
+      list << @objects.find("Overloading#params_only_in_overloads")
+      list.each do |m|
+        assert_equal 100, m.score, "#{m.fullname} did not get 100"
+      end
+    end
 
-  def test_manual_getset2
-    m = @objects.find("InchTest#manual_getset=")
-    refute m.getter?
-    assert m.setter?, "should be a setter"
-    refute m.has_doc?
-    assert_equal 0, m.score
-  end
+    it "should work with a malformed @param tag in an overload tag" do
+      m = @objects.find("Overloading#missing_param_names")
+      refute m.has_doc? # it may be mentioned in the docs, but it's malformed.
+    end
 
-  def test_attr_getset
-    m = @objects.find("InchTest#attr_getset")
-    assert m.getter?, "should be a getter"
-    refute m.setter?
-    refute m.has_doc?
-    assert_equal 0, m.score
-  end
+    it "should work with several overload tags on the same method" do
+      skip
+      m = @objects.find("Overloading#many_overloads")
+      assert_equal 1, count_roles(
+        m, Inch::Evaluation::Role::Method::WithoutReturnDescription)
+      assert_equal 1, count_roles(
+        m, Inch::Evaluation::Role::Method::WithoutReturnType)
+      assert_equal 1, count_roles(
+        m, Inch::Evaluation::Role::MethodParameter::WithoutMention, "block")
+    end
 
-  def test_attr_getset2
-    m = @objects.find("InchTest#attr_getset=")
-    refute m.getter?
-    assert m.setter?, "should be a setter"
-    refute m.has_doc?
-    assert_equal 0, m.score
-  end
+    it "should work if @param tags are only present in the @overload tags, but not on the actual method" do
+      m = @objects.find("Overloading#params_only_in_overloads")
+      unexpected_roles = [
+        Inch::Evaluation::Role::Object::WithoutCodeExample,
+        Inch::Evaluation::Role::MethodParameter::WithoutMention,
+        Inch::Evaluation::Role::MethodParameter::WithoutType
+      ]
+      assert_roles m, [], unexpected_roles
+    end
 
-  def test_struct_getset
-    m = @objects.find("InchTest::StructGetSet#struct_getset")
-    assert m.getter?, "should be a getter"
-    refute m.setter?
-    refute m.has_doc?
-    assert_equal 0, m.score
+    it "should work with one param missing in the overload tag" do
+      m = @objects.find("Overloading#one_param_missing_in_overload")
+      unexpected_roles = [
+        Inch::Evaluation::Role::Object::WithoutCodeExample
+      ]
+      expected_roles = [
+        Inch::Evaluation::Role::MethodParameter::WithoutMention,
+        Inch::Evaluation::Role::MethodParameter::WithoutType
+      ]
+      assert_roles m, expected_roles, unexpected_roles
+    end
   end
 
-  def test_struct_getset2
-    m = @objects.find("InchTest::StructGetSet#struct_getset=")
-    refute m.getter?
-    assert m.setter?, "should be a setter"
-    refute m.has_doc?
-    assert_equal 0, m.score
-  end
+  describe "MISC" do
+    #
+    it "should recognize named parameters in Ruby 2.1" do
+      skip # unless RUBY_VERSION =~ /^2/
 
-  def test_splat_parameter_notation
-    # it should assign the same score whether the parameter is
-    # described with or without the splat (*) operator
-    m1 = @objects.find("Foo#method_with_splat_parameter")
-    m2 = @objects.find("Foo#method_with_splat_parameter2")
-    assert_equal 1, m1.parameters.size
-    assert_equal 1, m2.parameters.size
-    assert_equal m1.score, m2.score
-  end
+      m = @objects.find("Foo#method_with_named_parameter")
+      unexpected_roles = [
+        Inch::Evaluation::Role::MethodParameter::WithoutMention,
+        Inch::Evaluation::Role::MethodParameter::WithoutType
+      ]
+      assert_roles m, [], unexpected_roles
+    end
 
-  def test_alias_method
-    m1 = @objects.find("InchTest#_aliased_method")
-    m2 = @objects.find("InchTest#_alias_method")
-    assert_equal m1.score, m2.score
-  end
+    it "should recognize indented parameter documentation" do
+      skip # YARD cannot parse this
 
-  def test_overloading1
-    list = []
-    list << @objects.find("Overloading#rgb")
-    list << @objects.find("Overloading#rgba")
-    list << @objects.find("Overloading#change_color")
-    list << @objects.find("Overloading#mix")
-    list << @objects.find("Overloading#hooks")
-    list << @objects.find("Overloading#identifiers")
-    list << @objects.find("Overloading#params_only_in_overloads")
-    list.each do |m|
-      assert_equal 100, m.score, "#{m.fullname} did not get 100"
+      m = @objects.find("Foo#method_with_indented_param_tag")
+      unexpected_roles = [
+        Inch::Evaluation::Role::MethodParameter::WithoutMention,
+        Inch::Evaluation::Role::MethodParameter::WithoutType
+      ]
+      assert_roles m, [], unexpected_roles
     end
-  end
 
-  def test_overloading_with_bad_doc
-    m = @objects.find("Overloading#missing_param_names")
-    refute m.has_doc? # it may be mentioned in the docs, but it's malformed.
-  end
+    it "should recognize wrong parameter documentation" do
+      m = @objects.find("Foo::Bar#method_with_wrong_doc")
+      assert m.has_doc?
+      assert m.has_parameters?
+      assert m.return_mentioned?
+
+      assert_equal 4, m.parameters.size
+      p = m.parameter(:param1)
+      assert p.mentioned?         # mentioned in docs, correctly
+      refute p.wrongly_mentioned?
+      p = m.parameter(:param2)
+      refute p.mentioned?
+      refute p.wrongly_mentioned? # not mentioned in docs at all
+      p = m.parameter(:param3)
+      refute p.mentioned?
+      refute p.wrongly_mentioned? # not mentioned in docs at all
+
+      p = m.parameter(:param4)
+      assert p.mentioned?
+      assert p.wrongly_mentioned? # mentioned in docs, but not present
+
+      assert m.score
+    end
 
-  def test_overloading_with_bad_doc
-    m = @objects.find("Overloading#params_only_in_overloads")
-    unexpected_roles = [
-      Inch::Evaluation::Role::Object::WithoutCodeExample,
-      Inch::Evaluation::Role::MethodParameter::WithoutMention,
-      Inch::Evaluation::Role::MethodParameter::WithoutType,
-    ]
-    assert_roles m, [], unexpected_roles
-  end
+    it "should recognize fully-documented methods with parameters" do
+      m = @objects.find("Foo::Bar#method_with_full_doc")
+      assert m.has_doc?
+      assert m.has_parameters?
+      assert m.return_mentioned?
+
+      assert_equal 2, m.parameters.size
+      m.parameters.each do |param|
+        assert param.mentioned?
+        assert param.typed?
+        assert param.described?
+        refute param.wrongly_mentioned?
+      end
+
+      assert_equal 100, m.score
+    end
+
+    it "should recognize question mark methods" do
+      m = @objects.find("InchTest#question_mark_method?")
+      refute m.has_doc?
+      refute m.has_parameters?
+
+      # assert it is zero, because YARD auto-assigns tags to these
+      assert_equal 0, m.score
+    end
 
-  def test_overloading_with_half_bad_doc
-    m = @objects.find("Overloading#one_param_missing_in_overload")
-    unexpected_roles = [
-      Inch::Evaluation::Role::Object::WithoutCodeExample,
-    ]
-    expected_roles = [
-      Inch::Evaluation::Role::MethodParameter::WithoutMention,
-      Inch::Evaluation::Role::MethodParameter::WithoutType,
-    ]
-    assert_roles m, expected_roles, unexpected_roles
+    it "should recognize question mark methods with description" do
+      m = @objects.find("InchTest#question_mark_method_with_description?")
+      refute m.has_doc?
+      refute m.has_parameters?
+
+      assert m.score > 0
+      assert m.score >= 50 # TODO: don't use magic numbers
+    end
+
+    it "should recognize question mark methods with description and parameters" do
+      m = @objects.find("InchTest#method_with_description_and_parameters?")
+      refute m.has_doc?
+      assert m.has_parameters?
+
+      assert m.score > 0
+    end
+
+    it "should recognize the depth of methods" do
+      m = @objects.find("#root_method")
+      assert_equal 1, m.depth
+      m = @objects.find("InchTest#getter")
+      assert_equal 2, m.depth
+      m = @objects.find("Foo::Bar#method_without_doc")
+      assert_equal 3, m.depth
+    end
+
+    it "should recognize docs on class variables" do
+      m = @objects.find("Foo::@@class_variable")
+      assert m.has_doc?
+      refute m.undocumented?
+      assert_equal 100, m.score
+    end
   end
 end