yard 0.9.18 → 0.9.23

data/spec/handlers/method_condition_handler_spec.rb

@@ -1,15 +1,15 @@
-# frozen_string_literal: true
-require File.dirname(__FILE__) + '/spec_helper'
-
-RSpec.describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}MethodConditionHandler" do
-  before(:all) { parse_file :method_condition_handler_001, __FILE__ }
-
-  it "does not parse regular if blocks in methods" do
-    expect(Registry.at('#b')).to be nil
-  end
-
-  it "parses if/unless blocks in the form X if COND" do
-    expect(Registry.at('#c')).not_to be nil
-    expect(Registry.at('#d')).not_to be nil
-  end
-end
+# frozen_string_literal: true
+require File.dirname(__FILE__) + '/spec_helper'
+
+RSpec.describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}MethodConditionHandler" do
+  before(:all) { parse_file :method_condition_handler_001, __FILE__ }
+
+  it "does not parse regular if blocks in methods" do
+    expect(Registry.at('#b')).to be nil
+  end
+
+  it "parses if/unless blocks in the form X if COND" do
+    expect(Registry.at('#c')).not_to be nil
+    expect(Registry.at('#d')).not_to be nil
+  end
+end

data/spec/handlers/method_handler_spec.rb

@@ -1,190 +1,214 @@
-# frozen_string_literal: true
-require File.dirname(__FILE__) + '/spec_helper'
-
-RSpec.describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}MethodHandler" do
-  before(:all) do
-    log.enter_level(Logger::ERROR) do
-      parse_file :method_handler_001, __FILE__
-    end
-  end
-
-  it "adds methods to parent's #meths list" do
-    expect(P(:Foo).meths).to include(P("Foo#method1"))
-  end
-
-  it "parses and adds class methods (self.method2)" do
-    expect(P(:Foo).meths).to include(P("Foo.method2"))
-  end
-
-  it "parses and adds class methods from other namespaces (String.hello)" do
-    expect(P("String.hello")).to be_instance_of(CodeObjects::MethodObject)
-  end
-
-  [:[], :[]=, :allowed?, :/, :=~, :==, :`, :|, :*, :&, :%, :'^', :-@, :+@, :'~@'].each do |name|
-    it "allows valid method #{name}" do
-      expect(Registry.at("Foo##{name}")).not_to be nil
-    end
-  end
-
-  it "allows self.methname" do
-    expect(Registry.at("Foo.new")).not_to be nil
-  end
-
-  it "marks dynamic methods as such" do
-    expect(P('Foo#dynamic').dynamic?).to be true
-  end
-
-  it "shows that a method is explicitly defined (if it was originally defined implicitly by attribute)" do
-    expect(P('Foo#method1').is_explicit?).to be true
-  end
-
-  it "handles parameters" do
-    expect(P('Foo#[]').parameters).to eq [['key', "'default'"]]
-    expect(P('Foo#/').parameters).to eq [['x', "File.new('x', 'w')"], ['y', '2']]
-  end
-
-  it "handles opts = {} as parameter" do
-    expect(P('Foo#optsmeth').parameters).to eq [['x', nil], ['opts', '{}']]
-  end
-
-  it "handles &block as parameter" do
-    expect(P('Foo#blockmeth').parameters).to eq [['x', nil], ['&block', nil]]
-  end
-
-  it "handles double splats" do
-    expect(P('Foo#d_splat').parameters).to eq [["reg", nil], ["**opts", nil]]
-    expect(P('Foo#d_unnamed_splat').parameters).to eq []
-  end
-
-  it "handles overloads" do
-    meth = P('Foo#foo')
-
-    o1 = meth.tags(:overload).first
-    expect(o1.name).to eq :bar
-    expect(o1.parameters).to eq [['a', nil], ['b', "1"]]
-    expect(o1.tag(:return).type).to eq "String"
-
-    o2 = meth.tags(:overload)[1]
-    expect(o2.name).to eq :baz
-    expect(o2.parameters).to eq [['b', nil], ['c', nil]]
-    expect(o2.tag(:return).type).to eq "Fixnum"
-
-    o3 = meth.tags(:overload)[2]
-    expect(o3.name).to eq :bang
-    expect(o3.parameters).to eq [['d', nil], ['e', nil]]
-    expect(o3.docstring).to be_empty
-    expect(o3.docstring).to be_blank
-  end
-
-  it "sets a return tag if not set on #initialize" do
-    meth = P('Foo#initialize')
-
-    expect(meth).to have_tag(:return)
-    expect(meth.tag(:return).types).to eq ["Foo"]
-    expect(meth.tag(:return).text).to eq "a new instance of Foo"
-  end
-
-  %w(inherited included method_added method_removed method_undefined).each do |meth|
-    it "sets @private tag on #{meth} callback method if no docstring is set" do
-      expect(P('Foo.' + meth)).to have_tag(:private)
-    end
-  end
-
-  it "does not set @private tag on extended callback method since docstring is set" do
-    expect(P('Foo.extended')).not_to have_tag(:private)
-  end
-
-  it "adds @return [Boolean] tag to methods ending in ? without return types" do
-    meth = P('Foo#boolean?')
-    expect(meth).to have_tag(:return)
-    expect(meth.tag(:return).types).to eq ['Boolean']
-  end
-
-  it "adds Boolean type to return tag without types" do
-    meth = P('Foo#boolean2?')
-    expect(meth).to have_tag(:return)
-    expect(meth.tag(:return).types).to eq ['Boolean']
-  end
-
-  it "does not change return type for method ending in ? with return types set" do
-    meth = P('Foo#boolean3?')
-    expect(meth).to have_tag(:return)
-    expect(meth.tag(:return).types).to eq ['NotBoolean', 'nil']
-  end
-
-  it "does not change return type for method ending in ? with return types set by @overload" do
-    meth = P('Foo#rainy?')
-    expect(meth).to have_tag(:overload)
-    expect(meth.tag(:overload)).to have_tag(:return)
-    expect(meth).not_to have_tag(:return)
-  end
-
-  it "adds method writer to existing attribute" do
-    expect(Registry.at('Foo#attr_name')).to be_reader
-    expect(Registry.at('Foo#attr_name=')).to be_writer
-  end
-
-  it "adds method reader to existing attribute" do
-    expect(Registry.at('Foo#attr_name2')).to be_reader
-    expect(Registry.at('Foo#attr_name2=')).to be_writer
-  end
-
-  it "generates an options parameter if @option refers to an undocumented parameter" do
-    meth = P('Foo#auto_opts')
-    expect(meth).to have_tag(:param)
-    expect(meth.tag(:param).name).to eq "opts"
-    expect(meth.tag(:param).types).to eq ["Hash"]
-  end
-
-  it "raises an undocumentable error when a method is defined on an object instance" do
-    undoc_error "error = Foo; def error.at(foo) end"
-    expect(Registry.at('error')).to be nil
-  end
-
-  it "allows class method to be defined on constant reference object" do
-    expect(Registry.at('Foo.meth_on_const')).not_to be nil
-    expect(Registry.at('Foo.meth2_on_const')).not_to be nil
-  end
-
-  it "copies alias information on method (re-)definition to new method" do
-    expect(Registry.at('D').aliases).to be_empty
-    expect(Registry.at('D#b').is_alias?).to be false
-    expect(Registry.at('D#a').is_alias?).to be false
-  end
-
-  it "adds macros for class methods" do
-    macro = CodeObjects::MacroObject.find('prop')
-    expect(macro).not_to be nil
-    expect(macro.macro_data).to eq "@!method $1(value)\n$3\n@return [$2]"
-    expect(macro.method_object).to eq Registry.at('E.property')
-    expect(macro).to be_attached
-    obj = Registry.at('E#foo')
-    expect(obj).not_to be nil
-    expect(obj.docstring).to eq 'create a foo'
-    expect(obj.signature).to eq 'def foo(value)'
-    expect(obj.tag(:return).types).to eq ['String']
-  end
-
-  it "handles macros on any object" do
-    macro = CodeObjects::MacroObject.find('xyz')
-    expect(macro).not_to be nil
-    expect(macro.macro_data).to eq '@!method $1'
-  end
-
-  it "skips macros on instance methods" do
-    expect(Registry.at('E#a')).to be nil
-  end
-
-  it "warns if the macro name is invalid" do
-    expect(log).to receive(:warn).with(/Invalid directive.*@!macro/)
-    YARD.parse_string "class Foo\n# @!macro\ndef self.foo; end\nend"
-  end
-
-  it "handles 'def end' methods" do
-    obj = Registry.at('F::A#foo')
-    expect(obj).not_to be nil
-    obj = Registry.at('F::A#bar')
-    expect(obj).not_to be nil
-    expect(obj.docstring).to eq 'PASS'
-  end
-end
+# frozen_string_literal: true
+require File.dirname(__FILE__) + '/spec_helper'
+
+RSpec.describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}MethodHandler" do
+  before(:all) do
+    log.enter_level(Logger::ERROR) do
+      parse_file :method_handler_001, __FILE__
+    end
+  end
+
+  it "adds methods to parent's #meths list" do
+    expect(P(:Foo).meths).to include(P("Foo#method1"))
+  end
+
+  it "parses and adds class methods (self.method2)" do
+    expect(P(:Foo).meths).to include(P("Foo.method2"))
+  end
+
+  it "parses and adds class methods from other namespaces (String.hello)" do
+    expect(P("String.hello")).to be_instance_of(CodeObjects::MethodObject)
+  end
+
+  [:[], :[]=, :allowed?, :/, :=~, :==, :`, :|, :*, :&, :%, :'^', :-@, :+@, :'~@'].each do |name|
+    it "allows valid method #{name}" do
+      expect(Registry.at("Foo##{name}")).not_to be nil
+    end
+  end
+
+  it "allows self.methname" do
+    expect(Registry.at("Foo.new")).not_to be nil
+  end
+
+  it "marks dynamic methods as such" do
+    expect(P('Foo#dynamic').dynamic?).to be true
+  end
+
+  it "shows that a method is explicitly defined (if it was originally defined implicitly by attribute)" do
+    expect(P('Foo#method1').is_explicit?).to be true
+  end
+
+  it "handles parameters" do
+    expect(P('Foo#[]').parameters).to eq [['key', "'default'"]]
+    expect(P('Foo#/').parameters).to eq [['x', "File.new('x', 'w')"], ['y', '2']]
+  end
+
+  it "handles multiline parameters" do
+    YARD.parse_string <<-EOF
+      class Bar
+        def multiline_params(x,
+          y, z, zz = 'zz',
+          *foo,
+          a: 'a', b: 'b',
+          c: 'c',
+          **bar,
+          &blk
+        )
+        end
+      end
+    EOF
+
+    sig = "def multiline_params(x, y, z, zz = 'zz', *foo, a: 'a', b: 'b', c: 'c', **bar, &blk)"
+    expect(P('Bar#multiline_params').signature).to eq sig
+  end if YARD.ruby2?
+
+  it "handles method signature with no parameters" do
+    YARD.parse_string "class Bar; def foo; end end"
+    expect(P('Bar#foo').signature).to eq 'def foo'
+  end
+
+  it "handles opts = {} as parameter" do
+    expect(P('Foo#optsmeth').parameters).to eq [['x', nil], ['opts', '{}']]
+  end
+
+  it "handles &block as parameter" do
+    expect(P('Foo#blockmeth').parameters).to eq [['x', nil], ['&block', nil]]
+  end
+
+  it "handles double splats" do
+    expect(P('Foo#d_splat').parameters).to eq [["reg", nil], ["**opts", nil]]
+    expect(P('Foo#d_unnamed_splat').parameters).to eq []
+  end
+
+  it "handles overloads" do
+    meth = P('Foo#foo')
+
+    o1 = meth.tags(:overload).first
+    expect(o1.name).to eq :bar
+    expect(o1.parameters).to eq [['a', nil], ['b', "1"]]
+    expect(o1.tag(:return).type).to eq "String"
+
+    o2 = meth.tags(:overload)[1]
+    expect(o2.name).to eq :baz
+    expect(o2.parameters).to eq [['b', nil], ['c', nil]]
+    expect(o2.tag(:return).type).to eq "Fixnum"
+
+    o3 = meth.tags(:overload)[2]
+    expect(o3.name).to eq :bang
+    expect(o3.parameters).to eq [['d', nil], ['e', nil]]
+    expect(o3.docstring).to be_empty
+    expect(o3.docstring).to be_blank
+  end
+
+  it "sets a return tag if not set on #initialize" do
+    meth = P('Foo#initialize')
+
+    expect(meth).to have_tag(:return)
+    expect(meth.tag(:return).types).to eq ["Foo"]
+    expect(meth.tag(:return).text).to eq "a new instance of Foo"
+  end
+
+  %w(inherited included method_added method_removed method_undefined).each do |meth|
+    it "sets @private tag on #{meth} callback method if no docstring is set" do
+      expect(P('Foo.' + meth)).to have_tag(:private)
+    end
+  end
+
+  it "does not set @private tag on extended callback method since docstring is set" do
+    expect(P('Foo.extended')).not_to have_tag(:private)
+  end
+
+  it "adds @return [Boolean] tag to methods ending in ? without return types" do
+    meth = P('Foo#boolean?')
+    expect(meth).to have_tag(:return)
+    expect(meth.tag(:return).types).to eq ['Boolean']
+  end
+
+  it "adds Boolean type to return tag without types" do
+    meth = P('Foo#boolean2?')
+    expect(meth).to have_tag(:return)
+    expect(meth.tag(:return).types).to eq ['Boolean']
+  end
+
+  it "does not change return type for method ending in ? with return types set" do
+    meth = P('Foo#boolean3?')
+    expect(meth).to have_tag(:return)
+    expect(meth.tag(:return).types).to eq ['NotBoolean', 'nil']
+  end
+
+  it "does not change return type for method ending in ? with return types set by @overload" do
+    meth = P('Foo#rainy?')
+    expect(meth).to have_tag(:overload)
+    expect(meth.tag(:overload)).to have_tag(:return)
+    expect(meth).not_to have_tag(:return)
+  end
+
+  it "adds method writer to existing attribute" do
+    expect(Registry.at('Foo#attr_name')).to be_reader
+    expect(Registry.at('Foo#attr_name=')).to be_writer
+  end
+
+  it "adds method reader to existing attribute" do
+    expect(Registry.at('Foo#attr_name2')).to be_reader
+    expect(Registry.at('Foo#attr_name2=')).to be_writer
+  end
+
+  it "generates an options parameter if @option refers to an undocumented parameter" do
+    meth = P('Foo#auto_opts')
+    expect(meth).to have_tag(:param)
+    expect(meth.tag(:param).name).to eq "opts"
+    expect(meth.tag(:param).types).to eq ["Hash"]
+  end
+
+  it "raises an undocumentable error when a method is defined on an object instance" do
+    undoc_error "error = Foo; def error.at(foo) end"
+    expect(Registry.at('error')).to be nil
+  end
+
+  it "allows class method to be defined on constant reference object" do
+    expect(Registry.at('Foo.meth_on_const')).not_to be nil
+    expect(Registry.at('Foo.meth2_on_const')).not_to be nil
+  end
+
+  it "copies alias information on method (re-)definition to new method" do
+    expect(Registry.at('D').aliases).to be_empty
+    expect(Registry.at('D#b').is_alias?).to be false
+    expect(Registry.at('D#a').is_alias?).to be false
+  end
+
+  it "adds macros for class methods" do
+    macro = CodeObjects::MacroObject.find('prop')
+    expect(macro).not_to be nil
+    expect(macro.macro_data).to eq "@!method $1(value)\n$3\n@return [$2]"
+    expect(macro.method_object).to eq Registry.at('E.property')
+    expect(macro).to be_attached
+    obj = Registry.at('E#foo')
+    expect(obj).not_to be nil
+    expect(obj.docstring).to eq 'create a foo'
+    expect(obj.signature).to eq 'def foo(value)'
+    expect(obj.tag(:return).types).to eq ['String']
+  end
+
+  it "handles macros on any object" do
+    macro = CodeObjects::MacroObject.find('xyz')
+    expect(macro).not_to be nil
+    expect(macro.macro_data).to eq '@!method $1'
+  end
+
+  it "skips macros on instance methods" do
+    expect(Registry.at('E#a')).to be nil
+  end
+
+  it "warns if the macro name is invalid" do
+    expect(log).to receive(:warn).with(/Invalid directive.*@!macro/)
+    YARD.parse_string "class Foo\n# @!macro\ndef self.foo; end\nend"
+  end
+
+  it "handles 'def end' methods" do
+    obj = Registry.at('F::A#foo')
+    expect(obj).not_to be nil
+    obj = Registry.at('F::A#bar')
+    expect(obj).not_to be nil
+    expect(obj.docstring).to eq 'PASS'
+  end
+end

data/spec/handlers/mixin_handler_spec.rb

@@ -1,56 +1,60 @@
-# frozen_string_literal: true
-require File.dirname(__FILE__) + '/spec_helper'
-
-RSpec.describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}MixinHandler" do
-  before(:all) { parse_file :mixin_handler_001, __FILE__ }
-
-  it "handles includes from classes or modules" do
-    expect(Registry.at(:X).instance_mixins).to include(P(:A))
-    expect(Registry.at(:Y).instance_mixins).to include(P(:A))
-  end
-
-  it "handles includes in class << self" do
-    expect(Registry.at(:Y).class_mixins).to include(P(:A))
-  end
-
-  it "handles includes for modules that don't yet exist" do
-    expect(Registry.at(:X).instance_mixins).to include(P(nil, :NOTEXIST))
-  end
-
-  it "sets the type of non-existing modules to :module" do
-    o = Registry.at(:X).instance_mixins.find {|obj| obj.name == :NOTEXIST }
-    expect(o.type).to eq :module
-  end
-
-  it "handles includes with multiple parameters" do
-    expect(Registry.at(:X)).not_to be nil
-  end
-
-  it "handles complex include statements" do
-    expect(P(:Y).instance_mixins).to include(P('B::C'))
-    expect(P(:Y).instance_mixins).to include(P(:B))
-  end
-
-  it "treats a mixed in Constant by taking its value as the real object name" do
-    expect(P(:Y).instance_mixins).to include(Registry.at('B::D'))
-  end
-
-  it "adds includes in the correct order when include is given multiple arguments" do
-    expect(P(:Z).instance_mixins).to eq [P(:A), P(:B)]
-  end
-
-  it "avoids including self for unresolved mixins of the same name" do
-    expect(P("ABC::DEF::FOO").mixins).to eq [P("ABC::FOO")]
-    expect(P("ABC::DEF::BAR").mixins).to eq [P("ABC::BAR")]
-  end
-
-  it "raises undocumentable error if argument is variable" do
-    undoc_error "module X; include invalid; end"
-    expect(Registry.at('X').mixins).to eq []
-  end
-
-  it "parses all other arguments before erroring out on undocumentable error" do
-    undoc_error "module X; include invalid, Y; end"
-    expect(Registry.at('X').mixins).to eq [P('Y')]
-  end
-end
+# frozen_string_literal: true
+require File.dirname(__FILE__) + '/spec_helper'
+
+RSpec.describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}MixinHandler" do
+  before(:all) { parse_file :mixin_handler_001, __FILE__ }
+
+  it "handles includes from classes or modules" do
+    expect(Registry.at(:X).instance_mixins).to include(P(:A))
+    expect(Registry.at(:Y).instance_mixins).to include(P(:A))
+  end
+
+  it "handles includes in class << self" do
+    expect(Registry.at(:Y).class_mixins).to include(P(:A))
+  end
+
+  it "handles includes for modules that don't yet exist" do
+    expect(Registry.at(:X).instance_mixins).to include(P(nil, :NOTEXIST))
+  end
+
+  it "sets the type of non-existing modules to :module" do
+    o = Registry.at(:X).instance_mixins.find {|obj| obj.name == :NOTEXIST }
+    expect(o.type).to eq :module
+  end
+
+  it "handles includes with multiple parameters" do
+    expect(Registry.at(:X)).not_to be nil
+  end
+
+  it "handles complex include statements" do
+    expect(P(:Y).instance_mixins).to include(P('B::C'))
+    expect(P(:Y).instance_mixins).to include(P(:B))
+  end
+
+  it "treats a mixed in Constant by taking its value as the real object name" do
+    expect(P(:Y).instance_mixins).to include(Registry.at('B::D'))
+  end
+
+  it "adds includes in the correct order when include is given multiple arguments" do
+    expect(P(:Z).instance_mixins).to eq [P(:A), P(:B)]
+  end
+
+  it "avoids including self for unresolved mixins of the same name" do
+    expect(P("ABC::DEF::FOO").mixins).to eq [P("ABC::FOO")]
+    expect(P("ABC::DEF::BAR").mixins).to eq [P("ABC::BAR")]
+  end
+
+  it "raises undocumentable error if argument is variable" do
+    undoc_error "module X; include invalid; end"
+    expect(Registry.at('X').mixins).to eq []
+  end
+
+  it "parses all other arguments before erroring out on undocumentable error" do
+    undoc_error "module X; include invalid, Y; end"
+    expect(Registry.at('X').mixins).to eq [P('Y')]
+  end
+
+  it "adds mixins from include calls to constants" do
+    expect(P('FromConstant').instance_mixins).to eq [P('A')]
+  end
+end