yard 0.4.0 → 0.5.0

data/spec/templates/examples/module001.txt

@@ -28,6 +28,6 @@ Class methods:
 Instance methods:
 -----------------
 
-    a
+    a, test_multi_overload, test_overload, void_meth
 
 

data/spec/templates/helpers/base_helper_spec.rb

@@ -81,14 +81,14 @@ describe YARD::Templates::Helpers::BaseHelper do
   describe '#format_object_type' do
     it "should return Exception if type is Exception" do
       obj = mock(:object)
-      obj.stub!(:class).and_return(YARD::CodeObjects::ClassObject)
+      obj.stub!(:is_a?).with(YARD::CodeObjects::ClassObject).and_return(true)
       obj.stub!(:is_exception?).and_return(true)
       format_object_type(obj).should == "Exception"
     end
     
     it "should return Class if type is Class" do
       obj = mock(:object)
-      obj.stub!(:class).and_return(YARD::CodeObjects::ClassObject)
+      obj.stub!(:is_a?).with(YARD::CodeObjects::ClassObject).and_return(true)
       obj.stub!(:is_exception?).and_return(false)
       format_object_type(obj).should == "Class"
     end

data/spec/templates/helpers/html_helper_spec.rb

@@ -1,7 +1,9 @@
 require File.dirname(__FILE__) + '/../../spec_helper'
+require File.dirname(__FILE__) + "/shared_signature_examples"
 
 describe YARD::Templates::Helpers::HtmlHelper do
   include YARD::Templates::Helpers::HtmlHelper
+  include YARD::Templates::Helpers::MethodHelper
 
   describe '#h' do
     it "should use #h to escape HTML" do
@@ -77,6 +79,25 @@ describe YARD::Templates::Helpers::HtmlHelper do
       stub!(:serializer).and_return nil
       link_object(CodeObjects::NamespaceObject.new(nil, :YARD), 'title').should == "title"
     end
+
+    it "should link objects from overload tag" do
+      YARD.parse_string <<-'eof'
+        module Foo
+          class Bar; def a; end end
+          class Baz
+            # @overload a
+            def a; end
+          end
+        end
+      eof
+      obj = Registry.at('Foo::Baz#a').tag(:overload)
+      foobar = Registry.at('Foo::Bar')
+      foobaz = Registry.at('Foo::Baz')
+      serializer = Serializers::FileSystemSerializer.new
+      stub!(:serializer).and_return(serializer)
+      stub!(:object).and_return(obj)
+      link_object("Bar#a").should =~ %r{href="Bar.html#a-instance_method"}
+    end
   end
 
   describe '#url_for' do
@@ -186,4 +207,66 @@ describe YARD::Templates::Helpers::HtmlHelper do
       }
     end
   end
+
+  describe '#signature' do
+    before do
+      @results = {
+        :regular => "- (Object) <strong>foo</strong>",
+        :default_return => "- (Hello) <strong>foo</strong>",
+        :no_default_return => "- <strong>foo</strong>",
+        :private_class => "+ (Object) <strong>foo</strong>  <span class=\"extras\">(private)</span>",
+        :single => "- (String) <strong>foo</strong>",
+        :two_types => "- (String, Symbol) <strong>foo</strong>",
+        :two_types_multitag => "- (String, Symbol) <strong>foo</strong>",
+        :type_nil => "- (Type<sup>?</sup>) <strong>foo</strong>",
+        :type_array => "- (Type<sup>+</sup>) <strong>foo</strong>",
+        :multitype => "- (Type, ...) <strong>foo</strong>",
+        :void => "- (void) <strong>foo</strong>",
+        :hide_void => "- <strong>foo</strong>",
+        :block => "- (Object) <strong>foo</strong> {|a, b, c| ... }"
+      }
+    end
+    
+    def format_types(types, brackets = false) types.join(", ") end
+    def signature(obj) super(obj, false).strip end
+    
+    it_should_behave_like "signature"
+  end
+  
+  describe '#html_syntax_highlight' do
+    before do
+      stub!(:options).and_return(:no_highlight => false)
+    end
+    
+    it "should return empty string on nil input" do
+      html_syntax_highlight(nil).should == ''
+    end
+    
+    it "should call #html_syntax_highlight_ruby by default" do
+      should_receive(:html_syntax_highlight_ruby).with('def x; end')
+      html_syntax_highlight('def x; end')
+    end
+    
+    it "should call html_syntax_highlight_NAME if source starts with !!!NAME" do
+      should_receive(:respond_to?).with('html_syntax_highlight_NAME').and_return(true)
+      should_receive(:html_syntax_highlight_NAME).and_return("foobar")
+      html_syntax_highlight(<<-eof
+        !!!NAME
+        def x; end
+      eof
+      ).should == "foobar"
+    end
+    
+    it "should not highlight if :no_highlight option is true" do
+      stub!(:options).and_return(:no_highlight => true)
+      should_not_receive(:html_syntax_highlight_ruby)
+      html_syntax_highlight('def x; end').should == 'def x; end'
+    end
+    
+    it "should not highlight if there is no highlight method specified by !!!NAME" do
+      should_receive(:respond_to?).with('html_syntax_highlight_NAME').and_return(false)
+      should_not_receive(:html_syntax_highlight_NAME)
+      html_syntax_highlight("!!!NAME\ndef x; end").should == "def x; end"
+    end
+  end
 end

data/spec/templates/helpers/method_helper_spec.rb

@@ -0,0 +1,47 @@
+require File.dirname(__FILE__) + "/../spec_helper"
+
+describe YARD::Templates::Helpers::MethodHelper do
+  include YARD::Templates::Helpers::BaseHelper
+  include YARD::Templates::Helpers::MethodHelper
+  
+  describe '#format_block' do
+    before { YARD::Registry.clear }
+    
+    it "should show block for method with yield" do
+      YARD.parse_string <<-'eof'
+        def foo; yield(a, b, c) end
+      eof
+      format_block(Registry.at('#foo')).should == "{|a, b, c| ... }"
+    end
+    
+    it "should show block for method with @yieldparam tags" do
+      YARD.parse_string <<-'eof'
+        # @yieldparam _self me!
+        def foo; end
+      eof
+      format_block(Registry.at('#foo')).should == "{|_self| ... }"
+    end
+
+    it "should show block for method with @yield but no types" do
+      YARD.parse_string <<-'eof'
+        # @yield blah
+        # @yieldparam a
+        def foo; end
+        
+        # @yield blah
+        def foo2; end
+      eof
+      format_block(Registry.at('#foo')).should == "{|a| ... }"
+      format_block(Registry.at('#foo2')).should == "{ ... }"
+    end
+    
+    it "should show block for method with @yield and types" do
+      YARD.parse_string <<-'eof'
+        # @yield [a, b, c] blah
+        # @yieldparam a
+        def foo; end
+      eof
+      format_block(Registry.at('#foo')).should == "{|a, b, c| ... }"
+    end
+  end
+end

data/spec/templates/helpers/shared_signature_examples.rb

@@ -0,0 +1,102 @@
+shared_examples_for "signature" do
+  before do
+    YARD::Registry.clear 
+    stub!(:options).and_return(:default_return => "Object")
+  end
+
+  it "should show signature for regular instance method" do
+    YARD.parse_string "def foo; end"
+    signature(Registry.at('#foo')).should == @results[:regular]
+  end
+
+  it "should allow default return type to be changed" do
+    stub!(:options).and_return(:default_return => "Hello")
+    YARD.parse_string "def foo; end"
+    signature(Registry.at('#foo')).should == @results[:default_return]
+  end
+
+  it "should allow default return type to be omitted" do
+    stub!(:options).and_return(:default_return => "")
+    YARD.parse_string "def foo; end"
+    signature(Registry.at('#foo')).should == @results[:no_default_return]
+  end
+
+  it "should show signature for private class method" do
+    YARD.parse_string "class A; private; def self.foo; end end"
+    signature(Registry.at('A.foo')).should == @results[:private_class]
+  end
+
+  it "should show return type for single type" do
+    YARD.parse_string <<-'eof'
+      # @return [String]
+      def foo; end
+    eof
+    signature(Registry.at('#foo')).should == @results[:single]
+  end
+
+  it "should show return type for 2 types" do
+    YARD.parse_string <<-'eof'
+      # @return [String, Symbol]
+      def foo; end
+    eof
+    signature(Registry.at('#foo')).should == @results[:two_types]
+  end
+
+  it "should show return type for 2 types over multiple tags" do
+    YARD.parse_string <<-'eof'
+      # @return [String]
+      # @return [Symbol]
+      def foo; end
+    eof
+    signature(Registry.at('#foo')).should == @results[:two_types_multitag]
+  end
+
+  it "should show 'Type?' if return types are [Type, nil]" do
+    YARD.parse_string <<-'eof'
+      # @return [Type, nil]
+      def foo; end
+    eof
+    signature(Registry.at('#foo')).should == @results[:type_nil]
+  end
+
+  it "should show 'Type+' if return types are [Type, Array<Type>]" do
+    YARD.parse_string <<-'eof'
+      # @return [Type, <Type>]
+      def foo; end
+    eof
+    signature(Registry.at('#foo')).should == @results[:type_array]
+  end
+
+  it "should (Type, ...) for more than 2 return types" do
+    YARD.parse_string <<-'eof'
+      # @return [Type, <Type>]
+      # @return [AnotherType]
+      def foo; end
+    eof
+    signature(Registry.at('#foo')).should == @results[:multitype]
+  end
+
+  it "should show (void) for @return [void] by default" do
+    YARD.parse_string <<-'eof'
+      # @return [void]
+      def foo; end
+    eof
+    signature(Registry.at('#foo')).should == @results[:void]
+  end
+
+  it "should not show return for @return [void] if :hide_void_return is true" do
+    stub!(:options).and_return(:hide_void_return => true)
+    YARD.parse_string <<-'eof'
+      # @return [void]
+      def foo; end
+    eof
+    signature(Registry.at('#foo')).should == @results[:hide_void]
+  end
+
+  it "should show block for method with yield" do
+    YARD.parse_string <<-'eof'
+      def foo; yield(a, b, c) end
+    eof
+    signature(Registry.at('#foo')).should == @results[:block]
+  end
+end

data/spec/templates/helpers/text_helper_spec.rb

@@ -0,0 +1,31 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+require File.dirname(__FILE__) + "/shared_signature_examples"
+
+describe YARD::Templates::Helpers::TextHelper do
+  include YARD::Templates::Helpers::TextHelper
+  include YARD::Templates::Helpers::MethodHelper
+  
+  describe '#signature' do
+    before do
+      @results = {
+        :regular => "root.foo -> Object",
+        :default_return => "root.foo -> Hello",
+        :no_default_return => "root.foo",
+        :private_class => "A.foo -> Object (private)",
+        :single => "root.foo -> String",
+        :two_types => "root.foo -> (String, Symbol)",
+        :two_types_multitag => "root.foo -> (String, Symbol)",
+        :type_nil => "root.foo -> Type?",
+        :type_array => "root.foo -> Type+",
+        :multitype => "root.foo -> (Type, ...)",
+        :void => "root.foo -> void",
+        :hide_void => "root.foo",
+        :block => "root.foo {|a, b, c| ... } -> Object"
+      }
+    end
+    
+    def signature(obj) super(obj).strip end
+    
+    it_should_behave_like "signature"
+  end
+end

data/spec/templates/method_spec.rb

@@ -1,10 +1,24 @@
 require File.dirname(__FILE__) + '/spec_helper'
 
+# $COPY = :method001
+# $COPYT = :html
+
 describe YARD::Templates::Engine.template(:default, :method) do
   before { Registry.clear }
   
+  shared_examples_for "all formats" do
+    it "should render html format correctly" do
+      html_equals(Registry.at('#m').format(:format => :html, :no_highlight => true), @template)
+    end
+    
+    it "should render text format correctly" do
+      text_equals(Registry.at('#m').format, @template)
+    end
+  end
+  
   describe 'regular (deprecated) method' do
     before do
+      @template = :method001
       YARD.parse_string <<-'eof'
         private
         # Comments
@@ -17,17 +31,12 @@ describe YARD::Templates::Engine.template(:default, :method) do
       eof
     end
     
-    it "should render html format correctly" do
-      html_equals(Registry.at('#m').format(:format => :html, :no_highlight => true), :method001)
-    end
-    
-    it "should render text format correctly" do
-      text_equals(Registry.at('#m').format, :method001)
-    end
+    it_should_behave_like "all formats"
   end
   
   describe 'method with 1 overload' do
     before do
+      @template = :method002
       YARD.parse_string <<-'eof'
         private
         # Comments
@@ -38,17 +47,12 @@ describe YARD::Templates::Engine.template(:default, :method) do
       eof
     end
     
-    it "should render html format correctly" do
-      html_equals(Registry.at('#m').format(:format => :html, :no_highlight => true), :method002)
-    end
-
-    it "should render text format correctly" do
-      text_equals(Registry.at('#m').format, :method002)
-    end
+    it_should_behave_like "all formats"
   end
   
   describe 'method with 2 overloads' do
     before do
+      @template = :method003
       YARD.parse_string <<-'eof'
         private
         # Method comments
@@ -64,12 +68,33 @@ describe YARD::Templates::Engine.template(:default, :method) do
       eof
     end
     
-    it "should render html format correctly" do
-      html_equals(Registry.at('#m').format(:format => :html, :no_highlight => true), :method003)
+    it_should_behave_like "all formats"
+  end
+  
+  describe 'method void return' do
+    before do
+      @template = :method004
+      YARD.parse_string <<-'eof'
+        # @return [void]
+        def m(*args) end
+      eof
     end
 
-    it "should render text format correctly" do
-      text_equals(Registry.at('#m').format, :method003)
+    it_should_behave_like "all formats"
+  end
+  
+  describe 'method void return in an overload' do
+    before do
+      @template = :method005
+      YARD.parse_string <<-'eof'
+        # @overload m(a)
+        #   @return [void]
+        # @overload m(b)
+        #   @param [String] b hi
+        def m(*args) end
+      eof
     end
+    
+    it_should_behave_like "all formats"
   end
 end

data/spec/templates/module_spec.rb

@@ -7,6 +7,8 @@ describe YARD::Templates::Engine.template(:default, :method) do
       module B
         def c; end
         def d; end
+        private
+        def e; end
       end
 
       # Comments
@@ -14,9 +16,28 @@ describe YARD::Templates::Engine.template(:default, :method) do
         attr_accessor :attr1
         attr_reader :attr2
         
+        # @overload attr3
+        #   @return [String] a string
+        # @overload attr3=(value)
+        #   @param [String] value sets the string
+        #   @return [void]
+        attr_accessor :attr3
+        
         def self.a; end
         def a; end
         alias b a
+
+        # @overload test_overload(a)
+        #   hello2
+        #   @param [String] a hi
+        def test_overload(*args) end
+          
+        # @overload test_multi_overload(a)
+        # @overload test_multi_overload(a, b)
+        def test_multi_overload(*args) end
+          
+        # @return [void]
+        def void_meth; end
         
         include B
         
@@ -31,7 +52,7 @@ describe YARD::Templates::Engine.template(:default, :method) do
   end
 
   it "should render html format correctly" do
-    html_equals(Registry.at('A').format(:format => :html, :no_highlight => true), :module001)
+    html_equals(Registry.at('A').format(:format => :html, :no_highlight => true, :hide_void_return => true, :visibilities => [:public]), :module001)
   end
 
   it "should render text format correctly" do