yard 0.9.24 → 0.9.25

data/spec/handlers/class_method_handler_shared_examples.rb

@@ -1,133 +0,0 @@
-# frozen_string_literal: true
-RSpec.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 do
-      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
-    end
-
-    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 do
-      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
-    end
-
-    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) do
-      <<-CODE
-        class SingletonClass
-          # Valid Ruby 2.1.0 syntax.
-          #{method_def}
-            'it works'
-          end
-        end
-      CODE
-    end
-
-    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(&: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

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

data/spec/handlers/constant_handler_spec.rb

@@ -1,112 +0,0 @@
-# frozen_string_literal: true
-require File.dirname(__FILE__) + '/spec_helper'
-
-RSpec.describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}ConstantHandler" do
-  before(:all) { parse_file :constant_handler_001, __FILE__ }
-
-  it "does not parse constants inside methods" do
-    expect(Registry.at("A::B::SOMECONSTANT").source).to eq "SOMECONSTANT= \"hello\""
-  end
-
-  it "only parses valid constants" do
-    expect(Registry.at("A::B::notaconstant")).to be nil
-  end
-
-  it "maintains newlines" do
-    expect(Registry.at("A::B::MYCONSTANT").value.delete("\r")).to eq "A +\nB +\nC +\nD"
-  end
-
-  it "turns Const = Struct.new(:sym) into class Const with attr :sym" do
-    obj = Registry.at("MyClass")
-    expect(obj).to be_kind_of(CodeObjects::ClassObject)
-    attrs = obj.attributes[:instance]
-    [:a, :b, :c].each do |key|
-      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 'documents block for Struct.new if present' do
-    obj = Registry.at("MyStructWithConstant")
-    expect(obj).to be_kind_of(CodeObjects::ClassObject)
-    expect(obj.constants[0].docstring).to eq 'A constant.'
-    expect(obj.constants[0].name).to eq :CONSTANT
-    expect(obj.constants[0].value).to eq "42"
-    expect(obj.constants[1].docstring).to eq 'Special constant (empty symbol)'
-    expect(obj.constants[1].name).to eq :EMPTY
-    expect(obj.constants[1].value).to eq ":''"
-  end
-
-  it "turns Const = Struct.new('Name', :sym) into class Const with attr :sym" do
-    obj = Registry.at("NotMyClass")
-    expect(obj).to be_kind_of(CodeObjects::ClassObject)
-    attrs = obj.attributes[:instance]
-    [:b, :c].each do |key|
-      expect(attrs).to have_key(key)
-      expect(attrs[key][:read]).not_to be nil
-      expect(attrs[key][:write]).not_to be nil
-    end
-
-    expect(Registry.at("NotMyClass2")).to be nil
-  end
-
-  it "turns Const = Struct.new into empty struct" do
-    obj = Registry.at("MyEmptyStruct")
-    expect(obj).not_to be nil
-    expect(obj.attributes[:instance]).to be_empty
-  end
-
-  it "maintains docstrings on structs defined via constants" do
-    obj = Registry.at("DocstringStruct")
-    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")
-    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 "raises undocumentable error in 1.9 parser for Struct.new assignment to non-const" do
-    undoc_error "nonconst = Struct.new"
-  end unless LEGACY_PARSER
-
-  %w(module class).each do |type|
-    it "does not allow #{type} to be redefined as constant" do
-      undoc_error <<-eof
-        #{type} Foo; end
-        Foo = "value"
-      eof
-    end
-  end unless LEGACY_PARSER
-
-  it "allows constant to have same name as constant in parent namespace" do
-    YARD.parse_string <<-eof
-      module A
-        class C; end
-        module B; C = 1 end
-      end
-    eof
-    expect(log.io.string).to eq ""
-    expect(Registry.at('A::B::C').type).to eq :constant
-  end
-
-  it "detects compound constant names" do
-    YARD.parse_string <<-eof
-      module A
-        class AA; end
-        AA::B = true
-      end
-      A::AA::C = true
-    eof
-
-    expect(Registry.at('A::AA::B').type).to eq :constant
-    expect(Registry.at('A::AA::C').type).to eq :constant
-  end if HAVE_RIPPER
-end

data/spec/handlers/decorator_handler_methods_spec.rb

@@ -1,393 +0,0 @@
-# frozen_string_literal: true
-require File.dirname(__FILE__) + '/spec_helper'
-
-RSpec.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, mname|
-              local_data[:method] = method
-              local_data[:node] = node
-              local_data[:name] = mname
-            end
-        end
-      end
-    end
-
-    # Generate method definition.
-    # @param symbols [Symbol] method names
-    # @return [String] method definition code
-    def make_defs(*symbols)
-      symbols.map do |s|
-        s = "self.#{s}" if mock_handler_opts[:scope] == :class
-        "def #{s}; end"
-      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) do
-      <<-eof
-      class #{class_name}
-        #{make_defs(*method_defs)}
-        # #{docstring}
-        mock_decorator #{param_string}
-      end
-      eof
-    end
-
-    before do
-      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
-    end
-
-    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) do
-          [:option_1, :baz, :bat, :option_2, :foo, :bar].map do |s|
-            make_ast s.inspect
-          end
-        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) do
-              ["def #{'self.' if mock_handler_opts[:scope] == :class}foo f1, f2; end",
-              "def #{'self.' if mock_handler_opts[:scope] == :class}bar b1, b2; end"]
-            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) do
-            <<-eof
-            class #{class_name}
-              # #{docstring}
-              mock_decorator :foo
-            end
-            eof
-          end
-
-          specify do
-            expect(subject).not_to respond_to :docstring
-          end
-        end
-
-        describe "to methods with existing docstring" do
-          let(:code) do
-            <<-eof
-            class #{class_name}
-
-              # original docstring
-              def foo; end
-
-              # #{docstring}
-              mock_decorator :foo
-            end
-            eof
-          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) do
-        <<-eof
-        class #{class_name}
-          #{make_defs(*method_defs)}
-          # #{docstring}
-          first_decorator second_decorator third_decorator #{param_string}
-        end
-        eof
-      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[-2].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
-    end
-  end # process_decorator
-end unless LEGACY_PARSER