yard 0.9.23 → 0.9.27

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

data/spec/handlers/dsl_handler_spec.rb

@@ -1,226 +0,0 @@
-# frozen_string_literal: true
-require File.dirname(__FILE__) + '/spec_helper'
-require 'ostruct'
-
-RSpec.describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}DSLHandler" do
-  before(:all) { parse_file :dsl_handler_001, __FILE__ }
-
-  it "creates a readable attribute when @!attribute r is found" do
-    obj = Registry.at('Foo#attr1')
-    expect(obj).not_to be nil
-    expect(obj).to be_reader
-    expect(obj.tag(:return).types).to eq ['Numeric']
-    expect(Registry.at('Foo#attr1=')).to be nil
-  end
-
-  it "creates a writable attribute when @!attribute w is found" do
-    obj = Registry.at('Foo#attr2=')
-    expect(obj).not_to be nil
-    expect(obj).to be_writer
-    expect(Registry.at('Foo#attr2')).to be nil
-  end
-
-  it "defaults to readwrite @!attribute" do
-    obj = Registry.at('Foo#attr3')
-    expect(obj).not_to be nil
-    expect(obj).to be_reader
-    obj = Registry.at('Foo#attr3=')
-    expect(obj).not_to be nil
-    expect(obj).to be_writer
-  end
-
-  it "allows @!attribute to define alternate method name" do
-    expect(Registry.at('Foo#attr4')).to be nil
-    expect(Registry.at('Foo#custom')).not_to be nil
-  end
-
-  it "defaults to creating an instance method for any DSL method with special tags" do
-    obj = Registry.at('Foo#implicit0')
-    expect(obj).not_to be nil
-    expect(obj.docstring).to eq "IMPLICIT METHOD!"
-    expect(obj.tag(:return).types).to eq ['String']
-  end
-
-  it "recognizes implicit docstring when it has scope tag" do
-    obj = Registry.at("Foo.implicit1")
-    expect(obj).not_to be nil
-    expect(obj.scope).to eq :class
-  end
-
-  it "recognizes implicit docstring when it has visibility tag" do
-    obj = Registry.at("Foo#implicit2")
-    expect(obj).not_to be nil
-    expect(obj.visibility).to eq :protected
-  end
-
-  it "does not recognize implicit docstring with any other normal tag" do
-    obj = Registry.at('Foo#implicit_invalid3')
-    expect(obj).to be nil
-  end
-
-  it "sets the method name when using @!method" do
-    obj = Registry.at('Foo.xyz')
-    expect(obj).not_to be nil
-    expect(obj.signature).to eq 'def xyz(a, b, c)'
-    expect(obj.parameters).to eq [['a', nil], ['b', nil], ['c', nil]]
-    expect(obj.source).to eq 'foo_bar'
-    expect(obj.docstring).to eq 'The foo method'
-  end
-
-  it "recognizes methods with no attached source" do
-    obj = Registry.at('Foo#no_src')
-    expect(obj).not_to be nil
-    expect(obj.signature).to eq 'def no_src'
-    expect(obj.source).to eq ''
-  end
-
-  it "allows setting of @!scope" do
-    expect(Registry.at('Foo.xyz').scope).to eq :class
-  end
-
-  it "creates module function if @!scope is module" do
-    mod_c = Registry.at('Foo.modfunc1')
-    mod_i = Registry.at('Foo#modfunc1')
-    expect(mod_c.scope).to eq :class
-    expect(mod_i.visibility).to eq :private
-  end
-
-  it "allows setting of @!visibility" do
-    expect(Registry.at('Foo.xyz').visibility).to eq :protected
-  end
-
-  it "ignores DSL methods without tags" do
-    expect(Registry.at('Foo#implicit_invalid')).to be nil
-  end
-
-  it "accepts a DSL method without tags if it has hash_flag (##)" do
-    expect(Registry.at('Foo#implicit_valid')).not_to be nil
-    expect(Registry.at('Foo#implicit_invalid2')).to be nil
-  end
-
-  it "allows creation of macros" do
-    macro = CodeObjects::MacroObject.find('property')
-    expect(macro).not_to be nil
-    expect(macro).not_to be_attached
-    expect(macro.method_object).to be nil
-  end
-
-  it "handles macros with no parameters to expand" do
-    expect(Registry.at('Foo#none')).not_to be nil
-    expect(Registry.at('Baz#none').signature).to eq 'def none(foo, bar)'
-  end
-
-  it "expands $N on method definitions" do
-    expect(Registry.at('Foo#regular_meth').docstring).to eq 'a b c'
-  end
-
-  it "applies new macro docstrings on new objects" do
-    obj = Registry.at('Foo#name')
-    expect(obj).not_to be nil
-    expect(obj.source).to eq 'property :name, String, :a, :b, :c'
-    expect(obj.signature).to eq 'def name(a, b, c)'
-    expect(obj.docstring).to eq 'A property that is awesome.'
-    expect(obj.tag(:param).name).to eq 'a'
-    expect(obj.tag(:param).text).to eq 'first parameter'
-    expect(obj.tag(:return).types).to eq ['String']
-    expect(obj.tag(:return).text).to eq 'the property name'
-  end
-
-  it "allows reuse of named macros" do
-    obj = Registry.at('Foo#age')
-    expect(obj).not_to be nil
-    expect(obj.source).to eq 'property :age, Fixnum, :value'
-    expect(obj.signature).to eq 'def age(value)'
-    expect(obj.docstring).to eq 'A property that is awesome.'
-    expect(obj.tag(:param).name).to eq 'value'
-    expect(obj.tag(:param).text).to eq 'first parameter'
-    expect(obj.tag(:return).types).to eq ['Fixnum']
-    expect(obj.tag(:return).text).to eq 'the property age'
-  end
-
-  it "knows about method information on DSL with macro expansion" do
-    expect(Registry.at('Foo#right_name')).not_to be nil
-    expect(Registry.at('Foo#right_name').source).to eq 'implicit_with_different_method_name :wrong, :right'
-    expect(Registry.at('Foo#wrong_name')).to be nil
-  end
-
-  it "uses attached macros" do
-    macro = CodeObjects::MacroObject.find('parser')
-    expect(macro.macro_data).to eq "@!method $1(opts = {})\n@return NOTHING!"
-    expect(macro).not_to be nil
-    expect(macro).to be_attached
-    expect(macro.method_object).to eq P('Foo.parser')
-    obj = Registry.at('Foo#c_parser')
-    expect(obj).not_to be nil
-    expect(obj.docstring).to eq ""
-    expect(obj.signature).to eq "def c_parser(opts = {})"
-    expect(obj.docstring.tag(:return).text).to eq "NOTHING!"
-  end
-
-  it "appends docstring on DSL method to attached macro" do
-    obj = Registry.at('Foo#d_parser')
-    expect(obj).not_to be nil
-    expect(obj.docstring).to eq "Another docstring"
-    expect(obj.signature).to eq "def d_parser(opts = {})"
-    expect(obj.docstring.tag(:return).text).to eq "NOTHING!"
-  end
-
-  it "only uses attached macros on methods defined in inherited hierarchy" do
-    expect(Registry.at('Bar#x_parser')).to be nil
-    expect(Registry.at('Baz#y_parser')).not_to be nil
-  end
-
-  it "looks through mixins for attached macros" do
-    meth = Registry.at('Baz#mixin_method')
-    expect(meth).not_to be nil
-    expect(meth.docstring).to eq 'DSL method mixin_method'
-  end
-
-  it "handles top-level DSL methods" do
-    obj = Registry.at('#my_other_method')
-    expect(obj).not_to be nil
-    expect(obj.docstring).to eq "Docstring for method"
-  end
-
-  it "handles Constant.foo syntax" do
-    obj = Registry.at('#beep')
-    expect(obj).not_to be nil
-    expect(obj.signature).to eq 'def beep(a, b, c)'
-  end
-
-  it "expands attached macros in first DSL method" do
-    expect(Registry.at('DSLMethods#foo').docstring).to eq "Returns String for foo"
-    expect(Registry.at('DSLMethods#bar').docstring).to eq "Returns Integer for bar"
-  end
-
-  it "does not detect implicit macros with invalid method names" do
-    undoc_error <<-eof
-      ##
-      # IMPLICIT METHOD THAT SHOULD
-      # NOT BE DETECTED
-      dsl_method '/foo/bar'
-    eof
-  end
-
-  it "warns on unparseable DSL statements" do
-    undoc_error "private(*foo(bar))"
-  end if HAVE_RIPPER
-
-  # @note Currently unsupported behavior. Overriding a macro on an alias will
-  #   not work until macro lookups can be done by caller_method directly.
-  # @todo optimize MacroObject lookup to work by caller name, not macro name.
-  it "cannot attach a macro on alias of attached macro" do
-    expect(Registry.at('AliasTest#main_foo1')).not_to be nil
-    expect(Registry.at('AliasTest#alt_foo1')).to be nil
-  end if HAVE_RIPPER
-
-  it "searches attached macro's aliases for caller method match" do
-    expect(Registry.at('AliasTest#main_foo2')).not_to be nil
-    expect(Registry.at('AliasTest#alt_foo2')).to be nil
-  end if HAVE_RIPPER
-
-  it "does not create method object if directive data detected in expanded macro" do
-    expect(Registry.at('DirectiveMethods#Bar')).to be nil
-    expect(Registry.at('DirectiveMethods').mixins).to include P(:Bar)
-  end
-end

data/spec/handlers/examples/alias_handler_001.rb.txt

@@ -1,46 +0,0 @@
-module A
-  def a; end
-  alias_method :b, :a
-  alias_method :"cstrmeth", :"a"
-
-  # Handle keyword syntax too
-  alias :c :a
-  alias :"cstrkey" :a
-  alias d? a
-  alias [] a
-  alias []= a
-  alias -@ a
-  alias % a
-  alias * a
-  alias for a
-  alias ConstantName a
-
-  # Handle quoted symbols
-  alias :'foo' :'a'
-end
-
-class C
-  def x; end
-end
-
-class B < C
-  alias_method(:q, :x)
-  alias_method :r?, :x
-  alias_method :s, :to_s
-  alias_method :t, :inspect if 500 == 3 * CONSTANT
-  alias_method :<<, :a
-  alias_method :for, :a
-  alias do x
-  alias x2 do
-end
-
-class D
-  # Foo bar
-  def a; "FOO" end
-
-  # @return [String]
-  alias b a
-
-  # @return [Numeric]
-  def a; 0 end
-end

data/spec/handlers/examples/attribute_handler_001.rb.txt

@@ -1,32 +0,0 @@
-module A
-  attr_writer :x
-end
-
-class B
-  class << self
-    attr_accessor :z
-  end
-
-  attr :a, true
-  attr :a2, false
-  attr :a3
-  # Docstring
-  attr_reader :b, :c, :d
-  attr_writer :e
-  attr_accessor 'f'
-
-  attr_accessor :z
-end
-
-class C
-  def foo; end
-  attr_writer :foo
-
-  def bar=(value); end
-  attr_reader :bar
-end
-
-class D
-protected
-attr_reader :parser
-end