yard 0.5.8 → 0.6.0

data/spec/core_ext/array_spec.rb

@@ -5,29 +5,10 @@ describe Array do
     it "should create an Insertion object" do
       [].place('x').should be_kind_of(Insertion)
     end
-  end
-end
-
-describe Insertion do
-  describe '#before' do
-    it "should place an object before another" do
-      [1, 2].place(3).before(2).should == [1, 3, 2]
-      [1, 2].place(3).before(1).should == [3, 1, 2]
-      [1, [4], 2].place(3).before(2).should == [1, [4], 3, 2]
-    end
-  end
-  
-  describe '#after' do
-    it "should place an object after another" do
-      [1, 2].place(3).after(2).should == [1, 2, 3]
-    end
-
-    it "should place an object after another and its subsections" do
-      [1, [2]].place(3).after(1).should == [1, [2], 3]
-    end
-
-    it "should not not ignore subsections if ignore_subections=false" do
-      [1, [2]].place(3).after(1, false).should == [1, 3, [2]]
+    
+    it "should allow multiple objects to be placed" do
+      [1, 2].place('x', 'y', 'z').before(2).should == [1, 'x', 'y', 'z', 2]
     end
   end
 end
+

data/spec/core_ext/insertion_spec.rb

@@ -0,0 +1,37 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe Insertion do
+  describe '#before' do
+    it "should place an object before another" do
+      [1, 2].place(3).before(2).should == [1, 3, 2]
+      [1, 2].place(3).before(1).should == [3, 1, 2]
+      [1, [4], 2].place(3).before(2).should == [1, [4], 3, 2]
+    end
+  end
+  
+  describe '#after' do
+    it "should place an object after another" do
+      [1, 2].place(3).after(2).should == [1, 2, 3]
+    end
+
+    it "should no longer place an object after another and its subsections (0.6)" do
+      [1, [2]].place(3).after(1).should == [1, 3, [2]]
+    end
+    
+    it "should place an array after an object" do
+      [1, 2, 3].place([4]).after(1).should == [1, [4], 2, 3]
+    end
+  end
+  
+  describe '#before_any' do
+    it "should place an object before another anywhere inside list (including sublists)" do
+      [1, 2, [3]].place(4).before_any(3).should == [1, 2, [4, 3]]
+    end
+  end
+
+  describe '#after_any' do
+    it "should place an object after another anywhere inside list (including sublists)" do
+      [1, 2, [3]].place(4).after_any(3).should == [1, 2, [3, 4]]
+    end
+  end
+end

data/spec/docstring_spec.rb

@@ -9,6 +9,26 @@ describe YARD::Docstring do
     end
   end
   
+  describe '#+' do
+    it "should add another Docstring" do
+      d = Docstring.new("FOO") + Docstring.new("BAR")
+      d.should == "FOO\nBAR"
+    end
+    
+    it "should copy over tags" do
+      d1 = Docstring.new("FOO\n@api private\n")
+      d2 = Docstring.new("BAR\n@param foo descr")
+      d = (d1 + d2)
+      d.should have_tag(:api)
+      d.should have_tag(:param)
+    end
+      
+    it "should add a String" do
+      d = Docstring.new("FOO") + "BAR"
+      d.should == "FOOBAR"
+    end
+  end
+  
   describe '#summary' do
     it "should handle empty docstrings" do
       o1 = Docstring.new
@@ -134,6 +154,10 @@ describe YARD::Docstring do
   end
   
   describe '#empty?/#blank?' do
+    before(:all) do
+      Tags::Library.define_tag "Invisible", :invisible_tag
+    end
+
     it "should be blank and empty if it has no content and no tags" do
       Docstring.new.should be_blank
       Docstring.new.should be_empty
@@ -158,6 +182,17 @@ describe YARD::Docstring do
       d.should be_empty
       d.should_not be_blank
     end
+    
+    it "should be blank if it has no visible tags" do
+      d = Docstring.new("@invisible_tag value")
+      d.should be_blank
+    end
+    
+    it "should not be blank if it has invisible tags and only_visible_tags = false" do
+      d = Docstring.new("@invisible_tag value")
+      d.add_tag Tags::Tag.new('invisible_tag', nil, nil)
+      d.blank?(false).should == false
+    end
   end
   
   describe '#add_tag' do
@@ -238,5 +273,33 @@ eof
 eof
       doc.tag(:param).text.should == "some value\nfoo bar\n baz"
     end
+
+    it "should allow numbers in tags" do
+      Tags::Library.define_tag(nil, :foo1)
+      Tags::Library.define_tag(nil, :foo2)
+      Tags::Library.define_tag(nil, :foo3)
+      doc = Docstring.new(<<-eof)
+@foo1 bar1
+@foo2 bar2
+@foo3 bar3
+eof
+      doc.tag(:foo1).text.should == "bar1"
+      doc.tag(:foo2).text.should == "bar2"
+    end
+    
+    it "should end tag on newline if next line is not indented" do
+      doc = Docstring.new(<<-eof)
+@author bar1
+@api bar2
+Hello world
+eof
+      doc.tag(:author).text.should == "bar1"
+      doc.tag(:api).text.should == "bar2"
+    end
+    
+    it "should warn about unknown tag" do
+      log.should_receive(:warn).with(/Unknown tag @hello$/)
+      Docstring.new("@hello world")
+    end
   end
 end

data/spec/handlers/attribute_handler_spec.rb

@@ -87,4 +87,8 @@ describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}AttributeHandler" do
   it "should add existing writer method as part of attr_reader combo" do
     Registry.at('C#foo').attr_info[:write].should == Registry.at('C#foo=')
   end
+  
+  it "should maintain visibility for attr_reader" do
+    Registry.at('D#parser').visibility.should == :protected
+  end
 end

data/spec/handlers/base_spec.rb

@@ -2,38 +2,110 @@ require File.dirname(__FILE__) + '/spec_helper'
 
 include Parser
 
-describe YARD::Handlers::Base, "#handles and inheritance" do
-  before do
-    Handlers::Base.stub!(:inherited)
-  end
-  
-  it "should keep track of subclasses" do
-    Handlers::Base.should_receive(:inherited).once
-    class TestHandler < Handlers::Base; end
-  end
+describe YARD::Handlers::Base do
+  describe "#handles and inheritance" do
+    before do
+      Handlers::Base.stub!(:inherited)
+    end
   
-  it "should raise NotImplementedError if process is called on a class with no #process" do
-    class TestNotImplementedHandler < Handlers::Base
+    it "should keep track of subclasses" do
+      Handlers::Base.should_receive(:inherited).once
+      class TestHandler < Handlers::Base; end
     end
+  
+    it "should raise NotImplementedError if process is called on a class with no #process" do
+      class TestNotImplementedHandler < Handlers::Base
+      end
     
-    lambda { TestNotImplementedHandler.new(0, 0).process }.should raise_error(NotImplementedError)
+      lambda { TestNotImplementedHandler.new(0, 0).process }.should raise_error(NotImplementedError)
+    end
+  
+    it "should allow multiple handles arguments" do
+      Handlers::Base.should_receive(:inherited).once
+      class TestHandler1 < Handlers::Base
+        handles :a, :b, :c
+      end
+      TestHandler1.handlers.should == [:a, :b, :c]
+    end
+
+    it "should allow multiple handles calls" do
+      Handlers::Base.should_receive(:inherited).once
+      class TestHandler2 < Handlers::Base
+        handles :a
+        handles :b
+        handles :c
+      end
+      TestHandler2.handlers.should == [:a, :b, :c]
+    end
   end
   
-  it "should allow multiple handles arguments" do
-    Handlers::Base.should_receive(:inherited).once
-    class TestHandler1 < Handlers::Base
-      handles :a, :b, :c
+  describe 'transitive tags' do
+    it "should add transitive tags to children" do
+      Registry.clear
+      YARD.parse_string <<-eof
+        # @since 1.0
+        # @author Foo
+        class A
+          def foo; end
+          # @since 1.1
+          def bar; end
+        end
+      eof
+      Registry.at('A').tag(:since).text.should == "1.0"
+      Registry.at('A#foo').tag(:since).text.should == "1.0"
+      Registry.at('A#bar').tag(:since).text.should == "1.1"
+      Registry.at('A#bar').tag(:author).should be_nil
     end
-    TestHandler1.handlers.should == [:a, :b, :c]
   end
-
-  it "should allow multiple handles calls" do
-    Handlers::Base.should_receive(:inherited).once
-    class TestHandler2 < Handlers::Base
-      handles :a
-      handles :b
-      handles :c
-    end
-    TestHandler2.handlers.should == [:a, :b, :c]
+  
+  describe '#push_state' do
+    def process(klass)
+      state = OpenStruct.new(:namespace => "ROOT", :scope => :instance, :owner => "ROOT")
+      klass.new(state, nil).process
+    end
+    
+    it "should push and return all old state info after block" do
+      class PushStateHandler1 < Handlers::Base
+        def process
+          push_state(:namespace => "FOO", :scope => :class, :owner => "BAR") do
+            namespace.should == "FOO"
+            scope.should == :class
+            owner.should == "BAR"
+          end
+          namespace.should == "ROOT"
+          owner.should == "ROOT"
+          scope.should == :instance
+        end
+      end
+      process PushStateHandler1
+    end
+    
+    it "should allow owner to be pushed individually" do
+      class PushStateHandler2 < Handlers::Base
+        def process
+          push_state(:owner => "BAR") do
+            namespace.should == "ROOT"
+            scope.should == :instance
+            owner.should == "BAR"
+          end
+          owner.should == "ROOT"
+        end
+      end
+      process PushStateHandler2
+    end
+    
+    it "should allow scope to be pushed individually" do
+      class PushStateHandler3 < Handlers::Base
+        def process
+          push_state(:scope => :foo) do
+            namespace.should == "ROOT"
+            scope.should == :foo
+            owner.should == "ROOT"
+          end
+          scope.should == :instance
+        end
+      end
+      process PushStateHandler3
+    end
   end
 end

data/spec/handlers/class_handler_spec.rb

@@ -1,4 +1,4 @@
-require File.dirname(__FILE__) + '/spec_helper'
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
 describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}ClassHandler" do
   before(:all) { parse_file :class_handler_001, __FILE__ }
@@ -230,4 +230,8 @@ describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}ClassHandler" do
     Registry.at("SemiDoccedStruct#fourth=").docstring.should == "sets the proc that writes stuff"
   end
     
+  it "should inherit from a regular struct" do
+    Registry.at('RegularStruct').superclass.should == P(:Struct)
+    Registry.at('RegularStruct2').superclass.should == P(:Struct)
+  end
 end

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

@@ -24,4 +24,9 @@ class C
 
   def bar=(value); end
   attr_reader :bar
+end
+
+class D
+protected
+attr_reader :parser
 end

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

@@ -83,6 +83,10 @@ end
 class Zebra
 end
 
+# A simple struct
+class RegularStruct < Struct; end
+class RegularStruct2 < ::Struct; end
+
 class Point < Struct.new(:x, :y, :z)
 end
 

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

@@ -17,4 +17,9 @@ end
 
 module ::Kernel
   def x; end
-end
+end
+
+module A; end
+module B; end
+module C; end
+class D; include A; include B; include C; end

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

@@ -17,4 +17,8 @@ class Testing
   def pub2; end
 
   protected :notpriv, 'notpriv2', :notpriv?
+  
+  private name
+  private *argument
+  private *(method_call)
 end

data/spec/handlers/method_handler_spec.rb

@@ -122,4 +122,9 @@ describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}MethodHandler" do
     meth.tag(:param).name.should == "opts"
     meth.tag(:param).types.should == ["Hash"]
   end
+  
+  it "should raise an undocumentable error when a method is defined on an object instance" do
+    undoc_error "error = Foo; def error.at(foo) end"
+    Registry.at('error').should be_nil
+  end
 end

data/spec/handlers/module_handler_spec.rb

@@ -23,4 +23,8 @@ describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}ModuleHandler" do
   it "should handle modules in the form ::ModName" do
     Registry.at("Kernel").should_not be_nil
   end
+  
+  it "should list mixins in proper order" do
+    Registry.at('D').mixins.should == [P(:C), P(:B), P(:A)]
+  end
 end

data/spec/handlers/visibility_handler_spec.rb

@@ -21,4 +21,10 @@ describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}VisibilityHandler" do
     Registry['Testing#notpriv2'].visibility.should == :protected
     Registry['Testing#notpriv?'].visibility.should == :protected
   end
+  
+  it "should only accept strings and symbols" do
+    Registry.at('Testing#name').should be_nil
+    Registry.at('Testing#argument').should be_nil
+    Registry.at('Testing#method_call').should be_nil
+  end
 end

data/spec/parser/source_parser_spec.rb

@@ -244,5 +244,29 @@ describe YARD::Parser::SourceParser do
         YARD::Parser::SourceParser.parse_string("$$$", :ruby)
       end
     end
+    
+    it "should handle groups" do
+      Registry.clear
+      YARD.parse_string <<-eof
+        class A
+          # @group Group Name
+          def foo; end
+          def foo2; end
+        
+          # @endgroup
+        
+          def bar; end
+          
+          # @group Group 2
+          def baz; end
+        end
+      eof
+      
+      Registry.at('A').groups.should == ['Group Name', 'Group 2']
+      Registry.at('A#bar').group.should be_nil
+      Registry.at('A#foo').group.should == "Group Name"
+      Registry.at('A#foo2').group.should == "Group Name"
+      Registry.at('A#baz').group.should == "Group 2"
+    end
   end
 end

data/spec/registry_spec.rb

@@ -73,13 +73,13 @@ describe YARD::Registry do
     end
   end
   
-  describe '#root' do
+  describe '.root' do
     it "should have an empty path for root" do
       Registry.root.path.should == ""
     end
   end
   
-  describe '#resolve' do
+  describe '.resolve' do
     it "should resolve any existing namespace" do
       o1 = ModuleObject.new(:root, :A)
       o2 = ModuleObject.new(o1, :B)
@@ -139,18 +139,18 @@ describe YARD::Registry do
     end
     
     it "should only check 'Path' in lookup on root namespace" do
-      Registry.instance.should_receive(:at).once.with('Test').and_return(true)
+      Registry.should_receive(:at).once.with('Test').and_return(true)
       Registry.resolve(Registry.root, "Test")
     end
     
     it "should not perform lookup by joining namespace and name without separator" do
       yard = ClassObject.new(:root, :YARD)
-      Registry.instance.should_not_receive(:at).with('YARDB')
+      Registry.should_not_receive(:at).with('YARDB')
       Registry.resolve(yard, 'B')
     end
   end
   
-  describe '#all' do
+  describe '.all' do
     it "should return objects of types specified by arguments" do
       ModuleObject.new(:root, :A)
       o1 = ClassObject.new(:root, :B)
@@ -167,7 +167,7 @@ describe YARD::Registry do
       r.should include(o1, o2)
     end
   
-    it "should allow #all to omit list" do
+    it "should allow .all to omit list" do
       o1 = ModuleObject.new(:root, :A)
       o2 = ClassObject.new(:root, :B)
       r = Registry.all
@@ -175,7 +175,7 @@ describe YARD::Registry do
     end
   end
   
-  describe '#paths' do
+  describe '.paths' do
     it "should return all object paths" do
       o1 = ModuleObject.new(:root, :A)
       o2 = ClassObject.new(:root, :B)
@@ -183,7 +183,7 @@ describe YARD::Registry do
     end
   end
   
-  describe '#load_yardoc' do
+  describe '.load_yardoc' do
     it "should delegate load to RegistryStore" do
       store = RegistryStore.new
       store.should_receive(:load).with('foo')
@@ -192,6 +192,10 @@ describe YARD::Registry do
       Registry.load_yardoc
     end
     
+    it "should return itself" do
+      Registry.load_yardoc.should == Registry
+    end
+    
     it "should maintain hash key equality on loaded objects" do
       Registry.clear
       Registry.load!(File.dirname(__FILE__) + '/serializers/data/serialized_yardoc')
@@ -200,4 +204,36 @@ describe YARD::Registry do
       Registry.at('Foo').aliases.has_key?(baz).should == true
     end
   end
+  
+  ['load', 'load_all', 'load!'].each do |meth|
+    describe('.' + meth) do
+      it "should return itself" do
+        Registry.send(meth).should == Registry
+      end
+    end
+  end
+  
+  describe '.each' do
+    before do 
+      YARD.parse_string "def a; end; def b; end; def c; end"
+    end
+    
+    after { Registry.clear }
+    
+    it "should iterate over .all" do
+      items = []
+      Registry.each {|x| items << x.path }
+      items.sort.should == ['#a', '#b', '#c']
+    end
+    
+    it "should include Enumerable and allow for find, select" do
+      Registry.find {|x| x.path == "#a" }.should be_a(CodeObjects::MethodObject)
+    end
+  end
+  
+  describe '.instance' do
+    it "should return itself" do
+      Registry.instance.should == Registry
+    end
+  end
 end