deg-yard 0.8.7.1

data/spec/templates/helpers/markup/rdoc_markup_spec.rb

@@ -0,0 +1,93 @@
+require File.dirname(__FILE__) + "/../../spec_helper"
+
+describe YARD::Templates::Helpers::Markup::RDocMarkup do
+  describe 'loading mechanism' do
+    before { @good_libs = [] }
+
+    def require(lib)
+      return true if @good_libs.include?(lib)
+      raise LoadError
+    end
+
+    def load_markup
+      begin
+        require 'rdoc/markup'
+        require 'rdoc/markup/to_html'
+        return :RDoc2
+      rescue LoadError
+        begin
+          require 'rdoc/markup/simple_markup'
+          require 'rdoc/markup/simple_markup/to_html'
+          return :RDoc1
+        rescue LoadError
+          raise NameError, "could not load RDocMarkup (rdoc is not installed)"
+        end
+      end
+    end
+
+    it "should load RDoc2.x if rdoc/markup is present" do
+      @good_libs += ['rdoc/markup', 'rdoc/markup/to_html']
+      load_markup.should == :RDoc2
+    end
+
+    it "should fail on RDoc2.x if rdoc/markup/to_html is not present" do
+      @good_libs += ['rdoc/markup']
+      lambda { load_markup }.should raise_error(NameError)
+    end
+
+    it "should load RDoc1.x if RDoc2 fails and rdoc/markup/simple_markup is present" do
+      @good_libs += ['rdoc/markup/simple_markup', 'rdoc/markup/simple_markup/to_html']
+      load_markup.should == :RDoc1
+    end
+
+    it "should error on loading if neither lib is present" do
+      lambda { load_markup }.should raise_error(NameError)
+    end
+  end
+
+  describe '#to_html' do
+    def to_html(text)
+      html = YARD::Templates::Helpers::Markup::RDocMarkup.new(text).to_html
+      html.strip.gsub(/\r?\n/, '')
+    end
+
+    it 'handles typewriter text' do
+      to_html('Hello +<code>+').should == '<p>Hello <tt>&lt;code&gt;</tt></p>'
+    end
+  end
+
+  describe '#fix_typewriter' do
+    def fix_typewriter(text)
+      YARD::Templates::Helpers::Markup::RDocMarkup.new('').send(:fix_typewriter, text)
+    end
+
+    it "should use #fix_typewriter to convert +text+ to <tt>text</tt>" do
+      fix_typewriter("Some +typewriter text &lt;+.").should ==
+        "Some <tt>typewriter text &lt;</tt>."
+      fix_typewriter("Not +typewriter text.").should ==
+        "Not +typewriter text."
+      fix_typewriter("Alternating +type writer+ text +here+.").should ==
+        "Alternating <tt>type writer</tt> text <tt>here</tt>."
+      fix_typewriter("No ++problem.").should ==
+        "No ++problem."
+      fix_typewriter("Math + stuff +is ok+").should ==
+        "Math + stuff <tt>is ok</tt>"
+      fix_typewriter("Hello +{Foo}+ World").should == "Hello <tt>{Foo}</tt> World"
+    end
+
+    it "should not apply to code blocks" do
+      fix_typewriter("<code>Hello +hello+</code>").should == "<code>Hello +hello+</code>"
+    end
+
+    it "should not apply to HTML tag attributes" do
+      fix_typewriter("<a href='http://foo.com/A+b+c'>A+b+c</a>").should ==
+        "<a href='http://foo.com/A+b+c'>A+b+c</a>"
+      fix_typewriter("<foo class='foo+bar+baz'/>").should ==
+        "<foo class='foo+bar+baz'/>"
+    end
+
+    it "should still apply inside of other tags" do
+      fix_typewriter("<p>+foo+</p>").should == "<p><tt>foo</tt></p>"
+    end
+  end
+end

data/spec/templates/helpers/markup_helper_spec.rb

@@ -0,0 +1,135 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+
+module YARD::Templates::Helpers::MarkupHelper
+  public :load_markup_provider, :markup_class, :markup_provider
+end
+
+class GeneratorMock
+  attr_accessor :options
+  include YARD::Templates::Helpers::MarkupHelper
+  def initialize(options = Templates::TemplateOptions.new)
+    self.options = options
+  end
+end
+
+describe YARD::Templates::Helpers::MarkupHelper do
+  before do
+    YARD::Templates::Helpers::MarkupHelper.clear_markup_cache
+  end
+
+  describe '#load_markup_provider' do
+    before do
+      log.stub!(:error)
+      @gen = GeneratorMock.new
+      @gen.options.reset_defaults
+    end
+
+    it "should exit on an invalid markup type" do
+      @gen.options.markup = :invalid
+      @gen.load_markup_provider.should == false
+    end
+
+    it "should fail on when an invalid markup provider is specified" do
+      @gen.options.update(:markup => :markdown, :markup_provider => :invalid)
+      @gen.load_markup_provider.should == false
+      @gen.markup_class.should == nil
+    end
+
+    it "should load RDocMarkup if rdoc is specified and it is installed" do
+      @gen.options.markup = :rdoc
+      @gen.load_markup_provider.should == true
+      @gen.markup_class.should == YARD::Templates::Helpers::Markup::RDocMarkup
+    end
+
+    it "should fail if RDoc cannot be loaded" do
+      @gen.options.markup = :rdoc
+      @gen.should_receive(:eval).with('::YARD::Templates::Helpers::Markup::RDocMarkup').and_raise(NameError)
+      @gen.load_markup_provider.should == false
+      @gen.markup_provider.should == nil
+    end
+
+    it "should search through available markup providers for the markup type if none is set" do
+      @gen.should_receive(:eval).with('::RedcarpetCompat').and_return(mock(:bluecloth))
+      @gen.should_receive(:require).with('redcarpet').and_return(true)
+      @gen.should_not_receive(:require).with('maruku')
+      @gen.options.markup = :markdown
+      # this only raises an exception because we mock out require to avoid
+      # loading any libraries but our implementation tries to return the library
+      # name as a constant
+      @gen.load_markup_provider.should == true
+      @gen.markup_provider.should == :redcarpet
+    end
+
+    it "should continue searching if some of the providers are unavailable" do
+      @gen.should_receive(:require).with('redcarpet').and_raise(LoadError)
+      @gen.should_receive(:require).with('rdiscount').and_raise(LoadError)
+      @gen.should_receive(:require).with('kramdown').and_raise(LoadError)
+      @gen.should_receive(:require).with('bluecloth').and_raise(LoadError)
+      @gen.should_receive(:require).with('maruku').and_raise(LoadError)
+      @gen.should_receive(:require).with('rpeg-markdown').and_return(true)
+      @gen.should_receive(:eval).with('::PEGMarkdown').and_return(true)
+      @gen.options.markup = :markdown
+      # this only raises an exception because we mock out require to avoid
+      # loading any libraries but our implementation tries to return the library
+      # name as a constant
+      @gen.load_markup_provider.should rescue nil
+      @gen.markup_provider.should == :"rpeg-markdown"
+    end
+
+    it "should override the search if `:markup_provider` is set in options" do
+      @gen.should_receive(:require).with('rdiscount').and_return(true)
+      @gen.should_receive(:eval).with('::RDiscount').and_return(true)
+      @gen.options.update(:markup => :markdown, :markup_provider => :rdiscount)
+      @gen.load_markup_provider.should rescue nil
+      @gen.markup_provider.should == :rdiscount
+    end
+
+    it "should fail if no provider is found" do
+      YARD::Templates::Helpers::MarkupHelper::MARKUP_PROVIDERS[:markdown].each do |p|
+        @gen.should_receive(:require).with(p[:lib].to_s).and_raise(LoadError)
+      end
+      @gen.options.markup = :markdown
+      @gen.load_markup_provider.should == false
+      @gen.markup_provider.should == nil
+    end
+
+    it "should fail if overridden provider is not found" do
+      @gen.should_receive(:require).with('rdiscount').and_raise(LoadError)
+      @gen.options.update(:markup => :markdown, :markup_provider => :rdiscount)
+      @gen.load_markup_provider.should == false
+      @gen.markup_provider.should == nil
+    end
+
+    it "should fail if the markup type is not found" do
+      log.should_receive(:error).with(/Invalid markup/)
+      @gen.options.markup = :xxx
+      @gen.load_markup_provider.should == false
+      @gen.markup_provider.should == nil
+    end
+  end
+
+  describe '#markup_for_file' do
+    include YARD::Templates::Helpers::MarkupHelper
+
+    it "should look for a shebang line" do
+      markup_for_file("#!text\ntext here", 'file.rdoc').should == :text
+    end
+
+    it "should return the default markup type if no shebang is found or no valid ext is found" do
+      stub!(:options).and_return(Options.new.update(:markup => :default_type))
+      markup_for_file('', 'filename').should == :default_type
+    end
+
+    it "should look for a file extension if no shebang is found" do
+      markup_for_file('', 'filename.MD').should == :markdown
+    end
+
+    Templates::Helpers::MarkupHelper::MARKUP_EXTENSIONS.each do |type, exts|
+      exts.each do |ext|
+        it "should recognize .#{ext} as #{type} markup type" do
+          markup_for_file('', "filename.#{ext}").should == type
+        end
+      end
+    end
+  end
+end

data/spec/templates/helpers/method_helper_spec.rb

@@ -0,0 +1,82 @@
+require File.dirname(__FILE__) + "/../spec_helper"
+
+describe YARD::Templates::Helpers::MethodHelper do
+  include YARD::Templates::Helpers::BaseHelper
+  include YARD::Templates::Helpers::MethodHelper
+
+  describe '#format_args' do
+    it "should display keyword arguments" do
+      params = [['a:', '1'], ['b:', '2'], ['**kwargs', nil]]
+      YARD.parse_string 'def foo; end'
+      Registry.at('#foo').stub(:parameters) { params }
+      format_args(Registry.at('#foo')).should == '(a: 1, b: 2, **kwargs)'
+    end
+
+    it "should not show &blockarg if no @param tag and has @yield" do
+      YARD.parse_string <<-'eof'
+        # @yield blah
+        def foo(&block); end
+      eof
+      format_args(Registry.at('#foo')).should == ''
+    end
+
+    it "should not show &blockarg if no @param tag and has @yieldparam" do
+      YARD.parse_string <<-'eof'
+        # @yieldparam blah test
+        def foo(&block); end
+      eof
+      format_args(Registry.at('#foo')).should == ''
+    end
+
+    it "should show &blockarg if @param block is documented (even with @yield)" do
+      YARD.parse_string <<-'eof'
+        # @yield [a,b]
+        # @yieldparam a test
+        # @param block test
+        def foo(&block) end
+      eof
+      format_args(Registry.at('#foo')).should == '(&block)'
+    end
+  end
+
+  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,123 @@
+shared_examples_for "signature" do
+  before do
+    YARD::Registry.clear
+    @options = Templates::TemplateOptions.new
+    @options.reset_defaults
+    stub!(:options).and_return(@options)
+  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
+    @options.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
+    @options.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, nil, nil] (extra nil)" do
+    YARD.parse_string <<-'eof'
+      # @return [Type, nil]
+      # @return [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
+    @options.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
+
+  it "should use regular return tag if the @overload is empty" do
+    YARD.parse_string <<-'eof'
+      # @overload foobar
+      #   Hello world
+      # @return [String]
+      def foo; end
+    eof
+    signature(Registry.at('#foo').tag(:overload)).should == @results[:empty_overload]
+  end
+end

data/spec/templates/helpers/text_helper_spec.rb

@@ -0,0 +1,44 @@
+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",
+        :empty_overload => 'root.foobar -> String'
+      }
+    end
+
+    def signature(obj) super(obj).strip end
+
+    it_should_behave_like "signature"
+  end
+
+  describe '#align_right' do
+    it "should align text right" do
+      text = "Method: #some_method (SomeClass)"
+      align_right(text).should == ' ' * 40 + text
+    end
+
+    it "should truncate text that is longer than allowed width" do
+      text = "(Defined in: /home/user/.rip/.packages/some_gem-2460672e333ac07b9190ade88ec9a91c/long/path.rb)"
+      align_right(text).should == ' ' + text[0,68] + '...'
+    end
+  end
+end

data/spec/templates/method_spec.rb

@@ -0,0 +1,102 @@
+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(html_options), @template)
+    end
+
+    it "should render text format correctly" do
+      text_equals(Registry.at('#m').format(text_options), @template)
+    end
+  end
+
+  describe 'regular (deprecated) method' do
+    before do
+      @template = :method001
+      YARD.parse_string <<-'eof'
+        private
+        # Comments
+        # @param [Hash] x the x argument
+        # @option x [String] :key1 (default) first key
+        # @option x [Symbol] :key2 second key
+        # @return [String] the result
+        # @raise [Exception] hi!
+        # @deprecated for great justice
+        def m(x) end
+        alias x m
+      eof
+    end
+
+    it_should_behave_like "all formats"
+  end
+
+  describe 'method with 1 overload' do
+    before do
+      @template = :method002
+      YARD.parse_string <<-'eof'
+        private
+        # Comments
+        # @overload m(x, y)
+        #   @param [String] x parameter x
+        #   @param [Boolean] y parameter y
+        def m(x) end
+      eof
+    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
+        # @overload m(x, y)
+        #   Overload docstring
+        #   @param [String] x parameter x
+        #   @param [Boolean] y parameter y
+        # @overload m(x, y, z)
+        #   @param [String] x parameter x
+        #   @param [Boolean] y parameter y
+        #   @param [Boolean] z parameter z
+        def m(*args) end
+      eof
+    end
+
+    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_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