yard 0.8.7.6 → 0.9.0

data/spec/handlers/class_method_handler_shared_examples.rb

@@ -0,0 +1,132 @@
+shared_examples "class method visibility decorator" do
+  # Use let(:visibility) to specify the name of the x_class_method
+  # visibility decorator to test.
+
+  describe do
+    before {
+      StubbedSourceParser.parse_string <<-CODE
+        class A
+          def self.b; end
+          def self.c; end
+          def self.d; end
+          def self.e; end
+
+          #{visibility}_class_method(:c, :d)
+          #{visibility}_class_method("e")
+        end
+      CODE
+    }
+
+    it "handles private_class_method statement" do
+      expect(Registry.at('A.c').visibility).to eq visibility
+      expect(Registry.at('A.d').visibility).to eq visibility
+      expect(Registry.at('A.e').visibility).to eq visibility
+    end
+
+    # Issue #760
+    # https://github.com/lsegal/yard/issues/760
+    it "handles singleton classes" do
+      # Note: It's important to def a method within the singleton class or
+      #       the bug may not trigger.
+      code = <<-CODE
+        class SingletonClass
+          private_class_method :new
+          def self.foo
+            "foo"
+          end
+        end
+      CODE
+
+      StubbedSourceParser.parse_string(code) # Should be successful.
+    end unless LEGACY_PARSER
+  end
+
+  describe "handles reopened class" do
+    before {
+      StubbedSourceParser.parse_string <<-CODE
+        class SingletonClass
+
+          #{'private' unless visibility.to_sym == :private}
+
+          # != visibility
+          def self.foo
+            'foo'
+          end
+
+          # == visibility
+          def self.bar
+          end
+
+          # == visibility from reopening class.
+          def self.baz
+          end
+
+          #{visibility}_class_method :new, :bar
+
+        end
+      CODE
+
+      StubbedSourceParser.parse_string <<-CODE
+        # Reopening singleton class.
+        class SingletonClass
+          #{visibility}_class_method :baz
+
+          #{'private' unless visibility.to_sym == :private}
+          # != visibility from reopened class. (Verifies class was reopened.)
+          def self.bat
+          end
+
+        end
+      CODE
+    }
+
+    specify do
+      expect(Registry.at('SingletonClass.foo').visibility).not_to eq visibility
+      expect(Registry.at('SingletonClass.bar').visibility).to     eq visibility
+      expect(Registry.at('SingletonClass.baz').visibility).to     eq visibility
+      expect(Registry.at('SingletonClass.bat').visibility).not_to eq visibility
+    end
+  end unless LEGACY_PARSER # reopened class
+
+  describe "as method definition decorator" do
+    subject { Registry.at('SingletonClass.foo') }
+
+    # Valid as of Ruby 2.1.0:
+    # private_class_method def self.foo; end
+
+    let(:code) {
+      <<-CODE
+        class SingletonClass
+          # Valid Ruby 2.1.0 syntax.
+          #{method_def}
+            'it works'
+          end
+        end
+      CODE
+    }
+
+    let(:method_def) { "#{visibility}_class_method def self.foo param1, param2" }
+
+    before { StubbedSourceParser.parse_string code }
+
+    it "handles self.foo" do
+      expect(subject.visibility).to eq visibility
+    end
+
+    it "handles parameters correctly" do
+      expect(subject.parameters.map { |p| p.first }).to eq ['param1', 'param2']
+    end
+
+    it "attaches documentation to method definition" do
+      expect(subject.docstring).to eq "Valid Ruby 2.1.0 syntax."
+    end
+
+    describe "handles SingletonClass.foo" do
+      let(:method_def) { "#{visibility}_class_method def SingletonClass.foo" }
+
+      specify do
+        expect(subject.visibility).to eq visibility
+      end
+    end
+  end unless LEGACY_PARSER
+end

data/spec/handlers/class_variable_handler_spec.rb

@@ -3,9 +3,9 @@ require File.dirname(__FILE__) + '/spec_helper'
 describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}ClassVariableHandler" do
   before(:all) { parse_file :class_variable_handler_001, __FILE__ }
 
-  it "should not parse class variables inside methods" do
+  it "does not parse class variables inside methods" do
     obj = Registry.at("A::B::@@somevar")
-    obj.source.should == "@@somevar = \"hello\""
-    obj.value.should == '"hello"'
+    expect(obj.source).to eq "@@somevar = \"hello\""
+    expect(obj.value).to eq '"hello"'
   end
 end

data/spec/handlers/constant_handler_spec.rb

@@ -3,62 +3,65 @@ require File.dirname(__FILE__) + '/spec_helper'
 describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}ConstantHandler" do
   before(:all) { parse_file :constant_handler_001, __FILE__ }
 
-  it "should not parse constants inside methods" do
-    Registry.at("A::B::SOMECONSTANT").source.should == "SOMECONSTANT= \"hello\""
+  it "does not parse constants inside methods" do
+    expect(Registry.at("A::B::SOMECONSTANT").source).to eq "SOMECONSTANT= \"hello\""
   end
 
-  it "should only parse valid constants" do
-    Registry.at("A::B::notaconstant").should be_nil
+  it "only parses valid constants" do
+    expect(Registry.at("A::B::notaconstant")).to be nil
   end
 
-  it "should maintain newlines" do
-    Registry.at("A::B::MYCONSTANT").value.gsub("\r", "").should == "A +\nB +\nC +\nD"
+  it "maintains newlines" do
+    expect(Registry.at("A::B::MYCONSTANT").value.gsub("\r", "")).to eq "A +\nB +\nC +\nD"
   end
 
-  it "should turn Const = Struct.new(:sym) into class Const with attr :sym" do
+  it "turns Const = Struct.new(:sym) into class Const with attr :sym" do
     obj = Registry.at("MyClass")
-    obj.should be_kind_of(CodeObjects::ClassObject)
+    expect(obj).to be_kind_of(CodeObjects::ClassObject)
     attrs = obj.attributes[:instance]
     [:a, :b, :c].each do |key|
-      attrs.should have_key(key)
-      attrs[key][:read].should_not be_nil
-      attrs[key][:write].should_not be_nil
+      expect(attrs).to have_key(key)
+      expect(attrs[key][:read]).not_to be nil
+      expect(attrs[key][:write]).not_to be nil
     end
   end
 
-  it "should turn Const = Struct.new('Name', :sym) into class Const with attr :sym" do
+  it "turns Const = Struct.new('Name', :sym) into class Const with attr :sym" do
     obj = Registry.at("NotMyClass")
-    obj.should be_kind_of(CodeObjects::ClassObject)
+    expect(obj).to be_kind_of(CodeObjects::ClassObject)
     attrs = obj.attributes[:instance]
     [:b, :c].each do |key|
-      attrs.should have_key(key)
-      attrs[key][:read].should_not be_nil
-      attrs[key][:write].should_not be_nil
+      expect(attrs).to have_key(key)
+      expect(attrs[key][:read]).not_to be nil
+      expect(attrs[key][:write]).not_to be nil
     end
 
-    Registry.at("NotMyClass2").should be_nil
+    expect(Registry.at("NotMyClass2")).to be nil
   end
 
-  it "should turn Const = Struct.new into empty struct" do
+  it "turns Const = Struct.new into empty struct" do
     obj = Registry.at("MyEmptyStruct")
-    obj.should_not be_nil
-    obj.attributes[:instance].should be_empty
+    expect(obj).not_to be nil
+    expect(obj.attributes[:instance]).to be_empty
   end
 
-  it "should maintain docstrings on structs defined via constants" do
+  it "maintains docstrings on structs defined via constants" do
     obj = Registry.at("DocstringStruct")
-    obj.should_not be_nil
-    obj.docstring.should == "A crazy struct."
-    obj.attributes[:instance].should_not be_empty
+    expect(obj).not_to be nil
+    expect(obj.docstring).to eq "A crazy struct."
+    expect(obj.attributes[:instance]).not_to be_empty
     a1 = Registry.at("DocstringStruct#bar")
     a2 = Registry.at("DocstringStruct#baz")
-    a1.docstring.should == "An attr"
-    a1.tag(:return).types.should == ["String"]
-    a2.docstring.should == "Another attr"
-    a2.tag(:return).types.should == ["Number"]
+    expect(a1.docstring).to eq "An attr"
+    expect(a1.tag(:return).types).to eq ["String"]
+    expect(a2.docstring).to eq "Another attr"
+    expect(a2.tag(:return).types).to eq ["Number"]
+    a3 = Registry.at("DocstringStruct#new_syntax")
+    expect(a3.docstring).to eq "Attribute defined with the new syntax"
+    expect(a3.tag(:return).types).to eq ["Symbol"]
   end
 
-  it "should raise undocumentable error in 1.9 parser for Struct.new assignment to non-const" do
+  it "raises undocumentable error in 1.9 parser for Struct.new assignment to non-const" do
     undoc_error "nonconst = Struct.new"
   end unless LEGACY_PARSER
 end

data/spec/handlers/decorator_handler_methods_spec.rb

@@ -0,0 +1,405 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe "YARD::Handlers::Ruby::DecoratorHandlerMethods" do
+  describe "#process_decorator" do
+
+    # Create a YARD decorator handler.
+    # @param name [Symbol] name of the mock decorator
+    def create_test_handler(name)
+      data[name] = {}
+
+      local_mock_handler_opts = mock_handler_opts
+      local_nodes = nodes
+      local_data = data[name]
+
+      Class.new YARD::Handlers::Ruby::Base do
+        include YARD::Handlers::Ruby::DecoratorHandlerMethods
+
+        handles method_call(:"#{name}_decorator")
+        namespace_only
+
+        process do
+          # process_decorator params written like this due to Ruby 1.8.
+          # A modern handler should splat local_nodes.
+          local_data[:return] =
+          process_decorator *(local_nodes + [local_mock_handler_opts]) do |method, node, name|
+            local_data[:method] = method
+            local_data[:node] = node
+            local_data[:name] = name
+          end
+        end
+      end
+    end
+
+    # Generate method definition.
+    # @param symbols [Symbol] method names
+    # @return [String] method definition code
+    def make_defs(*symbols)
+      symbols.map { |s|
+        s = "self.#{s}" if mock_handler_opts[:scope] == :class
+        "def #{s}; end"
+      }.join("\n")
+    end
+
+    # Generate an AST for the given source code string.
+    def make_ast(code)
+      YARD::Parser::Ruby::RubyParser.new(code, nil).parse.ast
+    end
+
+    subject { data[:mock] }
+
+    let(:data) { Hash.new }
+    let(:nodes) { [] }
+    let(:mock_handler_opts) { {:scope => :instance} }
+    let(:class_name)    { 'DecoratorTest' }
+    let(:docstring)     { 'the foo method' }
+    let(:param_string)  { 'def foo param1, param2; end' }
+    let(:method_defs)   { [] }
+    let(:method_string) { "#{class_name}#foo" }
+    let(:code) {"
+      class #{class_name}
+        #{make_defs *method_defs}
+        # #{docstring}
+        mock_decorator #{param_string}
+      end
+    "}
+
+    before {
+      Registry.clear
+      YARD::Handlers::Base.clear_subclasses
+
+      create_test_handler :mock
+      create_test_handler :first
+      create_test_handler :second
+      create_test_handler :third
+
+      StubbedSourceParser.parse_string code
+    }
+
+    it "returns an array of hashes containing the method proxy, node, and name" do
+      expect(subject[:return]).to be_an Array
+      expect(subject[:return].first[:name].to_s).to eq 'foo'
+      expect(subject[:return].first[:method].to_s).to eq method_string
+      expect(subject[:return].first[:node]).to be_a YARD::Parser::Ruby::AstNode
+    end
+
+    describe "method is a MethodObject if the method has been defined" do
+      let(:code) {"class DecoratorTest; mock_decorator def foo; end; end"}
+
+      specify do
+        expect(subject[:return].first[:method]) \
+          .to be_a YARD::CodeObjects::MethodObject
+      end
+    end
+
+    describe "method is a Proxy if the method has not been defined" do
+      let(:code) {"class DecoratorTest; mock_decorator :foo; end"}
+
+      specify do
+        expect(subject[:return].first[:method]).to be_a YARD::CodeObjects::Proxy
+      end
+    end
+
+    specify "block yields method proxy, node, name" do
+      expect(subject[:name]).to be_a Symbol
+      expect(subject[:name]).to eq :foo
+
+      expect(subject[:method]).to be_a YARD::CodeObjects::MethodObject
+      expect(subject[:method].to_s).to eq method_string
+
+      expect(subject[:node]).to be_a YARD::Parser::Ruby::AstNode
+    end
+
+    describe "capitalized method names" do
+      let(:method_defs)   { [:Foo] }
+      let(:param_string)  { 'def Foo param1, param2; end' }
+
+      specify do
+        expect(subject[:method].to_s).to eq "#{class_name}#Foo"
+      end
+    end
+
+    describe "nodes argument" do
+      subject { data[:mock][:return].map { |h| h[:method].to_s } }
+
+      describe "assumes all params refer to methods by default" do
+        let(:method_defs)  { [:foo, :bar] }
+        let(:param_string) { method_defs.map(&:inspect).join(',') }
+        let(:nodes) { [] }
+
+        specify do
+          expect(subject).to eq ["#{class_name}#foo", "#{class_name}#bar"]
+        end
+      end
+
+      describe "can specify which params to capture as methods" do
+        let(:method_defs) { [:foo, :bar, :baz, :bat] }
+        let(:parameters) {
+          [:option_1, :baz, :bat, :option_2, :foo, :bar].map do |s|
+            make_ast s.inspect
+          end
+        }
+
+        describe "as a single param" do
+          let(:nodes) { parameters[4] }
+
+          specify do
+            expect(subject).to eq ["#{class_name}#foo"]
+          end
+        end
+
+        describe "as a list of params" do
+          let(:nodes) { [parameters[4], parameters[5]] }
+
+          specify do
+            expect(subject).to eq ["#{class_name}#foo", "#{class_name}#bar"]
+          end
+        end
+
+        describe "as a range" do
+          let(:nodes) { parameters[4..-1] }
+
+          specify do
+            expect(subject).to eq ["#{class_name}#foo", "#{class_name}#bar"]
+          end
+        end
+
+        describe "as multiple ranges" do
+          # Written like this due to Ruby 1.8. Can also splat the ranges as
+          # separate params:
+          #   *parameters[1..2], *parameters[4..-1]
+          let(:nodes) { parameters[1..2] + parameters[4..-1] }
+
+          specify do
+            expect(subject).to eq [
+              "#{class_name}#baz",
+              "#{class_name}#bat",
+              "#{class_name}#foo",
+              "#{class_name}#bar"
+            ]
+          end
+        end
+      end
+
+      describe "can select no nodes by passing nil" do
+        let(:nodes) { [nil] }
+
+        specify do
+          expect(subject).to eq []
+        end
+      end
+    end
+
+    describe "scope option" do
+      describe "defaults to :instance" do
+        let(:mock_handler_opts) { {} }
+
+        specify do
+          expect(subject[:return].first[:method].to_s).to eq method_string
+        end
+      end
+
+      describe "creates method proxies" do
+
+        shared_examples "decorator helper scope" do
+          let(:param_string) { decorator_params.map(&:inspect).join(',') }
+
+          describe "for symbols" do
+            let(:decorator_params) { [:foo, :bar] }
+
+            specify do
+              expect(subject.count).to eq decorator_params.count
+
+              subject.each_with_index do |_, i|
+                expect(subject[i]).to be_a YARD::CodeObjects::MethodObject
+                expect(subject[i].to_s).to eq \
+                  "#{class_name}#{mock_handler_opts[:scope] == :class ? '.' : '#'}#{decorator_params[i]}"
+              end
+            end
+          end
+
+          describe "for string literals" do
+            let(:decorator_params) { ['foo', 'bar'] }
+
+            specify do
+              expect(subject.count).to eq decorator_params.count
+
+              subject.each_with_index do |_, i|
+                expect(subject[i]).to be_a YARD::CodeObjects::MethodObject
+                expect(subject[i].to_s).to eq \
+                  "#{class_name}#{mock_handler_opts[:scope] == :class ? '.' : '#'}#{decorator_params[i]}"
+              end
+            end
+          end
+
+          describe "for methods" do
+            let(:param_string) { decorator_params.join(',') }
+            let(:decorator_params) {[
+              "def #{'self.' if mock_handler_opts[:scope] == :class}foo f1, f2; end",
+              "def #{'self.' if mock_handler_opts[:scope] == :class}bar b1, b2; end"
+            ]}
+
+            specify do
+              expect(subject.count).to eq decorator_params.count
+
+              subject.each_with_index do |_, i|
+                expect(subject[i]).to be_a YARD::CodeObjects::MethodObject
+                expect(subject[i].to_s).to eq \
+                  class_name +
+                  (mock_handler_opts[:scope] == :class ? '.' : '#') +
+                  decorator_params[i].split(' ')[1][/\w+$/]
+              end
+            end
+          end
+        end # decorator helper scope shared examples
+
+        subject { data[:mock][:return].map { |h| h[:method] } }
+
+        let(:docstring) { 'the foo method' }
+        let(:method_defs) { [:foo, :bar] }
+
+        describe "for :instance" do
+          let(:mock_handler_opts) { {:scope => :instance} }
+
+          include_examples "decorator helper scope"
+        end
+
+        describe "for :class" do
+          let(:mock_handler_opts) { {:scope => :class} }
+
+          include_examples "decorator helper scope"
+        end
+      end
+    end
+
+    describe "docstring from decorator" do
+      subject { Registry.at method_string }
+
+      specify "attaches to method definitions as decorator parameters" do
+        expect(subject.docstring).to eq docstring
+      end
+
+      describe "does not attach" do
+        describe "to undefined methods" do
+          let(:code) {"
+            class #{class_name}
+              # #{docstring}
+              mock_decorator :foo
+            end
+          "}
+
+          specify do
+            expect(subject).not_to respond_to :docstring
+          end
+        end
+
+        describe "to methods with existing docstring" do
+          let(:code) {"
+            class #{class_name}
+
+              # original docstring
+              def foo; end
+
+              # #{docstring}
+              mock_decorator :foo
+            end
+          "}
+
+          specify do
+            expect(subject.docstring).to eq 'original docstring'
+          end
+        end
+      end
+    end
+
+    describe "chained decorators" do
+      subject { Registry.at method_string }
+
+      let(:param_string) { 'def foo param1, param2; end' }
+      let(:code) {"
+        class #{class_name}
+          #{make_defs *method_defs}
+          # #{docstring}
+          first_decorator second_decorator third_decorator #{param_string}
+        end
+      "}
+
+      specify "register nested method defs" do
+        expect(subject).to be_a YARD::CodeObjects::MethodObject
+      end
+
+      describe "transfer docstring to decorated method defs" do
+        specify do
+          expect(subject.docstring).to eq docstring
+        end
+
+        describe "unless opt-out param is set" do
+          let(:mock_handler_opts) { {:transfer_docstring => false} }
+
+          specify do
+            expect(subject.docstring.empty?).to be true
+          end
+        end
+      end
+
+      describe "don't transfer docstring to referenced methods" do
+        let(:method_defs)  { [:foo] }
+        let(:param_string) { ':foo' }
+
+        specify do
+          expect(subject.docstring.empty?).to be true
+        end
+      end
+
+      specify "don't transfer docstring to other decorators" do
+        expect(Registry.at("#{class_name}#second_decorator")) \
+          .not_to respond_to :docstring
+
+        expect(Registry.at("#{class_name}#third_decorator")) \
+          .not_to respond_to :docstring
+      end
+
+      describe "transfer source to decorated method defs" do 
+        specify do
+          expect(subject.source).to eq code.lines.to_a[-3].strip
+        end
+
+        describe "unless opt-out param is set" do
+          let(:mock_handler_opts) { {:transfer_source => false} }
+
+          specify do
+            expect(subject.source).to eq param_string
+          end
+        end
+      end
+
+      describe "don't transfer source to referenced methods" do
+        let(:method_defs)  { [:foo] }
+        let(:param_string) { ':foo' }
+
+        specify do
+          expect(subject.source).to eq make_defs(*method_defs)
+        end
+      end
+
+      describe "are tagged" do
+        let(:method_defs)  { [:foo, :bar] }
+        let(:param_string) { method_defs.map(&:inspect).join(',') }
+
+        specify do
+          expect(subject.tags.count).to eq 3
+
+          subject.tags.each do |tag|
+            expect(tag.tag_name).to eq 'decorator'
+          end
+
+          expect(subject.tags.map(&:text)).to eq [
+            'third_decorator',
+            'second_decorator',
+            'first_decorator'
+          ]
+        end
+      end
+    end
+  end # process_decorator
+end unless LEGACY_PARSER