yard 0.9.5 → 0.9.6

data/spec/tags/default_factory_spec.rb

@@ -1,6 +1,6 @@
-require File.dirname(__FILE__) + '/../spec_helper'
+# frozen_string_literal: true
 
-describe YARD::Tags::DefaultFactory do
+RSpec.describe YARD::Tags::DefaultFactory do
   before { @f = YARD::Tags::DefaultFactory.new }
 
   describe "#parse_tag" do
@@ -59,7 +59,7 @@ describe YARD::Tags::DefaultFactory do
       expect(a).to eq b
       expect(b).to eq c
       expect(c).to eq d
-      expect(a).to include(['a','b','c'])
+      expect(a).to include(['a', 'b', 'c'])
     end
 
     it "returns the text before the type list as the last element" do
@@ -158,5 +158,11 @@ describe YARD::Tags::DefaultFactory do
       expect(t.pair.defaults).to eq ["default"]
       expect(t.pair.text).to eq "description"
     end
+
+    it "allows omitting default" do
+      t = parse_options("xyz [Types] key")
+      expect(t.pair).to be_instance_of(Tags::DefaultTag)
+      expect(t.pair.name).to eq "key"
+    end
   end
-end
+end

data/spec/tags/default_tag_spec.rb

@@ -1,6 +1,6 @@
-require File.dirname(__FILE__) + '/../spec_helper'
+# frozen_string_literal: true
 
-describe YARD::Tags::DefaultTag do
+RSpec.describe YARD::Tags::DefaultTag do
   it "creates a tag with defaults" do
     o = YARD::Tags::DefaultTag.new('tagname', 'desc', ['types'], 'name', ['defaults'])
     expect(o.defaults).to eq ['defaults']
@@ -8,4 +8,4 @@ describe YARD::Tags::DefaultTag do
     expect(o.name).to eq 'name'
     expect(o.types).to eq ['types']
   end
-end
+end

data/spec/tags/directives_spec.rb

@@ -1,4 +1,4 @@
-require File.dirname(__FILE__) + "/../spec_helper"
+# frozen_string_literal: true
 
 def tag_parse(content, object = nil, handler = nil)
   @parser = DocstringParser.new
@@ -6,15 +6,15 @@ def tag_parse(content, object = nil, handler = nil)
   @parser
 end
 
-describe YARD::Tags::ParseDirective do
+RSpec.describe YARD::Tags::ParseDirective do
   describe "#call" do
     after { Registry.clear }
 
     it "parses if handler=nil but use file=(stdin)" do
-      tag_parse %{@!parse
+      tag_parse %(@!parse
         # Docstring here
         def foo; end
-      }
+      )
       expect(Registry.at('#foo').docstring).to eq "Docstring here"
       expect(Registry.at('#foo').file).to eq '(stdin)'
     end
@@ -36,7 +36,7 @@ describe YARD::Tags::ParseDirective do
           eval "def foo; end"
         end
       eof
-      parser = Parser::SourceParser.new
+      parser = YARD::Parser::SourceParser.new
       parser.file = "myfile.rb"
       parser.parse(StringIO.new(src))
       expect(Registry.at('A#foo').file).to eq 'myfile.rb'
@@ -44,7 +44,7 @@ describe YARD::Tags::ParseDirective do
   end
 end
 
-describe YARD::Tags::GroupDirective do
+RSpec.describe YARD::Tags::GroupDirective do
   describe "#call" do
     it "does nothing if handler=nil" do
       tag_parse("@!group foo")
@@ -58,7 +58,7 @@ describe YARD::Tags::GroupDirective do
   end
 end
 
-describe YARD::Tags::EndGroupDirective do
+RSpec.describe YARD::Tags::EndGroupDirective do
   describe "#call" do
     it "does nothing if handler=nil" do
       tag_parse("@!endgroup foo")
@@ -72,7 +72,7 @@ describe YARD::Tags::EndGroupDirective do
   end
 end
 
-describe YARD::Tags::MacroDirective do
+RSpec.describe YARD::Tags::MacroDirective do
   def handler
     OpenStruct.new(:call_params => %w(a b c),
                    :caller_method => 'foo',
@@ -161,7 +161,7 @@ describe YARD::Tags::MacroDirective do
   end
 end
 
-describe YARD::Tags::MethodDirective do
+RSpec.describe YARD::Tags::MethodDirective do
   describe "#call" do
     after { Registry.clear }
 
@@ -283,7 +283,7 @@ describe YARD::Tags::MethodDirective do
   end
 end
 
-describe YARD::Tags::AttributeDirective do
+RSpec.describe YARD::Tags::AttributeDirective do
   describe "#call" do
     after { Registry.clear }
 
@@ -369,7 +369,7 @@ describe YARD::Tags::AttributeDirective do
   end
 end
 
-describe YARD::Tags::ScopeDirective do
+RSpec.describe YARD::Tags::ScopeDirective do
   describe "#call" do
     after { Registry.clear }
 
@@ -407,7 +407,7 @@ describe YARD::Tags::ScopeDirective do
   end
 end
 
-describe YARD::Tags::VisibilityDirective do
+RSpec.describe YARD::Tags::VisibilityDirective do
   describe "#call" do
     after { Registry.clear }
 

data/spec/tags/library_spec.rb

@@ -1,6 +1,6 @@
-require File.dirname(__FILE__) + '/../spec_helper'
+# frozen_string_literal: true
 
-describe YARD::Tags::Library do
+RSpec.describe YARD::Tags::Library do
   def tag(docstring)
     Docstring.new(docstring).tags.first
   end
@@ -31,4 +31,18 @@ describe YARD::Tags::Library do
       expect(tag('@x.y.zz foo(bar)').signature).to eq 'foo(bar)'
     end
   end
+
+  describe "#tag.explain_types" do
+    it "can explain tag types" do
+      expect(tag("@return [A, B<String>]").explain_types).to eq "an A; a B of (Strings)"
+    end
+
+    it "returns nil if no types present" do
+      expect(tag("@return").explain_types).to eq nil
+    end
+
+    it "returns nil if types are not parseable" do
+      expect(tag("@return [$]").explain_types).to eq nil
+    end
+  end
 end

data/spec/tags/overload_tag_spec.rb

@@ -1,6 +1,6 @@
-require File.dirname(__FILE__) + '/../spec_helper'
+# frozen_string_literal: true
 
-describe YARD::Tags::OverloadTag do
+RSpec.describe YARD::Tags::OverloadTag do
   before do
     @tag = Tags::OverloadTag.new(:overload, <<-'eof')
       def bar(a, b = 1, &block)
@@ -42,7 +42,7 @@ describe YARD::Tags::OverloadTag do
     @tag.object = double(:object)
     expect(@tag.object).to receive(:is_a?).at_least(3).times.with(CodeObjects::Base).and_return(true)
     expect(@tag.is_a?(CodeObjects::Base)).to be true
-    expect(@tag.kind_of?(CodeObjects::Base)).to be true
+    expect(@tag.is_a?(CodeObjects::Base)).to be true
     expect(CodeObjects::Base === @tag).to be true
   end
 
@@ -50,4 +50,4 @@ describe YARD::Tags::OverloadTag do
     tag = Tags::OverloadTag.new(:overload, "default")
     expect(tag.signature).to eq "default"
   end
-end
+end

data/spec/tags/ref_tag_list_spec.rb

@@ -1,6 +1,6 @@
-require File.dirname(__FILE__) + '/../spec_helper'
+# frozen_string_literal: true
 
-describe YARD::Tags::RefTagList do
+RSpec.describe YARD::Tags::RefTagList do
   before { YARD::Registry.clear }
 
   it "accepts symbol or string as owner's path and convert it into a proxy" do
@@ -50,4 +50,4 @@ describe YARD::Tags::RefTagList do
       expect(t.owner).to eq o
     end
   end
-end
+end

data/spec/tags/types_explainer_spec.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+RSpec.describe YARD::Tags::TypesExplainer do
+  Type = YARD::Tags::TypesExplainer::Type
+  CollectionType = YARD::Tags::TypesExplainer::CollectionType
+  FixedCollectionType = YARD::Tags::TypesExplainer::FixedCollectionType
+  HashCollectionType = YARD::Tags::TypesExplainer::HashCollectionType
+  Parser = YARD::Tags::TypesExplainer::Parser
+
+  def parse(types)
+    Parser.new(types).parse
+  end
+
+  def parse_fail(types)
+    expect(lambda { parse(types) }).to raise_error(SyntaxError)
+  end
+
+  describe Type, '#to_s' do
+    before { @t = Type.new(nil) }
+
+    it "works for a class/module reference" do
+      @t.name = "ClassModuleName"
+      expect(@t.to_s).to eq "a ClassModuleName"
+      expect(@t.to_s(false)).to eq "ClassModuleNames"
+
+      @t.name = "XYZ"
+      expect(@t.to_s).to eq "a XYZ"
+      expect(@t.to_s(false)).to eq "XYZ's"
+
+      @t.name = "Array"
+      expect(@t.to_s).to eq "an Array"
+      expect(@t.to_s(false)).to eq "Arrays"
+    end
+
+    it "works for a method (ducktype)" do
+      @t.name = "#mymethod"
+      expect(@t.to_s).to eq "an object that responds to #mymethod"
+      expect(@t.to_s(false)).to eq "objects that respond to #mymethod"
+    end
+
+    it "works for a constant value" do
+      ['false', 'true', 'nil', '4'].each do |name|
+        @t.name = name
+        expect(@t.to_s).to eq name
+        expect(@t.to_s(false)).to eq name
+      end
+    end
+  end
+
+  describe CollectionType, '#to_s' do
+    before { @t = CollectionType.new("Array", nil) }
+
+    it "can contain one item" do
+      @t.types = [Type.new("Object")]
+      expect(@t.to_s).to eq "an Array of (Objects)"
+    end
+
+    it "can contain more than one item" do
+      @t.types = [Type.new("Object"), Type.new("String"), Type.new("Symbol")]
+      expect(@t.to_s).to eq "an Array of (Objects, Strings or Symbols)"
+    end
+
+    it "can contain nested collections" do
+      @t.types = [CollectionType.new("List", [Type.new("Object")])]
+      expect(@t.to_s).to eq "an Array of (a List of (Objects))"
+    end
+  end
+
+  describe FixedCollectionType, '#to_s' do
+    before { @t = FixedCollectionType.new("Array", nil) }
+
+    it "can contain one item" do
+      @t.types = [Type.new("Object")]
+      expect(@t.to_s).to eq "an Array containing (an Object)"
+    end
+
+    it "can contain more than one item" do
+      @t.types = [Type.new("Object"), Type.new("String"), Type.new("Symbol")]
+      expect(@t.to_s).to eq "an Array containing (an Object followed by a String followed by a Symbol)"
+    end
+
+    it "can contain nested collections" do
+      @t.types = [FixedCollectionType.new("List", [Type.new("Object")])]
+      expect(@t.to_s).to eq "an Array containing (a List containing (an Object))"
+    end
+  end
+
+  describe FixedCollectionType, '#to_s' do
+    before { @t = HashCollectionType.new("Hash", nil, nil) }
+
+    it "can contain a single key type and value type" do
+      @t.key_types = [Type.new("Object")]
+      @t.value_types = [Type.new("Object")]
+      expect(@t.to_s).to eq "a Hash with keys made of (Objects) and values of (Objects)"
+    end
+
+    it "can contain multiple key types" do
+      @t.key_types = [Type.new("Key"), Type.new("String")]
+      @t.value_types = [Type.new("Object")]
+      expect(@t.to_s).to eq "a Hash with keys made of (Keys or Strings) and values of (Objects)"
+    end
+
+    it "can contain multiple value types" do
+      @t.key_types = [Type.new("String")]
+      @t.value_types = [Type.new("true"), Type.new("false")]
+      expect(@t.to_s).to eq "a Hash with keys made of (Strings) and values of (true or false)"
+    end
+  end
+
+  describe Parser, '#parse' do
+    it "parses a regular class name" do
+      type = parse("MyClass")
+      expect(type.size).to eq 1
+      expect(type.first).to be_a(Type)
+      expect(type.first.name).to eq "MyClass"
+    end
+
+    it "parses a path reference name" do
+      type = parse("A::B")
+      expect(type.size).to eq 1
+      expect(type.first).to be_a(Type)
+      expect(type.first.name).to eq "A::B"
+    end
+
+    it "parses a list of simple names" do
+      type = parse("A, B::C, D, E")
+      expect(type.size).to eq 4
+      expect(type[0].name).to eq "A"
+      expect(type[1].name).to eq "B::C"
+      expect(type[2].name).to eq "D"
+      expect(type[3].name).to eq "E"
+    end
+
+    it "parses a collection type" do
+      type = parse("MyList<String>")
+      expect(type.first).to be_a(CollectionType)
+      expect(type.first.types.size).to eq 1
+      expect(type.first.name).to eq "MyList"
+      expect(type.first.types.first.name).to eq "String"
+    end
+
+    it "allows a collection type without a name" do
+      type = parse("<String>")
+      expect(type.first.name).to eq "Array"
+    end
+
+    it "allows a fixed collection type without a name" do
+      type = parse("(String)")
+      expect(type.first.name).to eq "Array"
+    end
+
+    it "allows a hash collection type without a name" do
+      type = parse("{K=>V}")
+      expect(type.first.name).to eq "Hash"
+    end
+
+    it "does not accept two commas in a row" do
+      parse_fail "A,,B"
+    end
+
+    it "does not accept two types not separated by a comma" do
+      parse_fail "A B"
+    end
+
+    it "does not allow a comma without a following type" do
+      parse_fail "A, "
+    end
+
+    it "fails on any unrecognized character" do
+      parse_fail "$"
+    end
+  end
+
+  describe ".explain" do
+    it "parses an arbitrarily nested collection type" do
+      explain = YARD::Tags::TypesExplainer.explain("Array<String, Array<Symbol, List(String, {K=>V})>>")
+      result = "an Array of (Strings or an Array of (Symbols or a List containing
+        (a String followed by a Hash with keys made of (K's) and values of (V's))))"
+      expect(explain).to eq result.delete("\n").squeeze(' ')
+    end
+
+    it "parses various examples" do
+      expect = {
+        "Fixnum, Foo, Object, true" => "a Fixnum; a Foo; an Object; true",
+        "#read" => "an object that responds to #read",
+        "Array<String, Symbol, #read>" => "an Array of (Strings, Symbols or objects that respond to #read)",
+        "Set<Number>" => "a Set of (Numbers)",
+        "Array(String, Symbol)" => "an Array containing (a String followed by a Symbol)",
+        "Hash{String => Symbol, Number}" => "a Hash with keys made of (Strings) and values of (Symbols or Numbers)",
+        "Array<Foo, Bar>, List(String, Symbol, #to_s), {Foo, Bar => Symbol, Number}" => "an Array of (Foos or Bars);
+          a List containing (a String followed by a Symbol followed by an object that responds to #to_s);
+          a Hash with keys made of (Foos or Bars) and values of (Symbols or Numbers)"
+      }
+      expect.each do |input, expected|
+        explain = YARD::Tags::TypesExplainer.explain(input)
+        expect(explain).to eq expected.delete("\n").squeeze(' ')
+      end
+    end
+  end
+end

data/spec/templates/class_spec.rb

@@ -1,6 +1,7 @@
+# frozen_string_literal: true
 require File.dirname(__FILE__) + '/spec_helper'
 
-describe YARD::Templates::Engine.template(:default, :docstring) do
+RSpec.describe YARD::Templates::Engine.template(:default, :docstring) do
   before do
     Registry.clear
     YARD.parse_string <<-'eof'

data/spec/templates/constant_spec.rb

@@ -1,6 +1,7 @@
+# frozen_string_literal: true
 require File.dirname(__FILE__) + "/spec_helper"
 
-describe YARD::Templates::Engine.template(:default, :constant) do
+RSpec.describe YARD::Templates::Engine.template(:default, :constant) do
   describe "fully dressed constant" do
     it "renders text format correctly" do
       YARD.parse_string <<-'eof'
@@ -37,4 +38,4 @@ describe YARD::Templates::Engine.template(:default, :constant) do
       text_equals(Registry.at('MYCONST').format(text_options), :constant003)
     end
   end
-end
+end

data/spec/templates/engine_spec.rb

@@ -1,6 +1,7 @@
+# frozen_string_literal: true
 require File.dirname(__FILE__) + '/spec_helper'
 
-describe YARD::Templates::Engine do
+RSpec.describe YARD::Templates::Engine do
   before { @paths = Engine.template_paths }
   after { Engine.template_paths = @paths }
 
@@ -60,14 +61,14 @@ describe YARD::Templates::Engine do
       paths = ['/full/path/template/name', '/full/path2/template/name']
       expect(Engine).to receive(:find_template_paths).with(nil, 'template').at_least(1).times.and_return([])
       expect(Engine).to receive(:find_template_paths).with(nil, 'template/name').and_return(paths)
-      ancestors = Engine.template('template/name').ancestors.map {|m| m.class_name }
+      ancestors = Engine.template('template/name').ancestors.map(&:class_name)
       expect(ancestors).to include("Template__full_path2_template_name")
     end
 
     it "includes parent directories before other template paths" do
       paths = ['/full/path/template/name', '/full/path2/template/name']
       expect(Engine).to receive(:find_template_paths).with(nil, 'template/name').and_return(paths)
-      ancestors = Engine.template('template/name').ancestors.map {|m| m.class_name }
+      ancestors = Engine.template('template/name').ancestors.map(&:class_name)
       expect(ancestors[0, 4]).to eq ["Template__full_path_template_name", "Template__full_path_template",
         "Template__full_path2_template_name", "Template__full_path2_template"]
     end