deg-yard 0.8.7.1

data/spec/templates/template_spec.rb

@@ -0,0 +1,409 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::Templates::Template do
+  def template(path)
+    YARD::Templates::Engine.template!(path, '/full/path/' + path.to_s)
+  end
+
+  before :each do
+    YARD::Templates::ErbCache.clear!
+  end
+
+  describe '.include_parent' do
+    it "should not include parent directory if parent directory is a template root path" do
+      mod = template('q')
+      mod.should_not include(template(''))
+    end
+
+    it "should include overridden parent directory" do
+      Engine.stub!(:template_paths).and_return(['/foo', '/bar'])
+      File.should_receive(:directory?).with('/foo/a/b').and_return(true)
+      File.should_receive(:directory?).with('/bar/a/b').and_return(false)
+      File.should_receive(:directory?).with('/foo/a').at_least(1).times.and_return(true)
+      File.should_receive(:directory?).with('/bar/a').at_least(1).times.and_return(true)
+      ancestors = Engine.template('a/b').ancestors.map {|c| c.class_name }
+      ancestors[0, 3].should == %w( Template__foo_a_b Template__bar_a Template__foo_a )
+    end
+
+    it "should include parent directory template if exists" do
+      mod1 = template('x')
+      mod2 = template('x/y')
+      mod2.should include(mod1)
+    end
+  end
+
+  describe '.full_paths' do
+    it "should list full_path" do
+      mod = template(:a)
+      mod.full_paths.should == ['/full/path/a']
+    end
+
+    it "should list paths of included modules" do
+      mod = template(:a)
+      mod.send(:include, template(:b))
+      mod.full_paths.should == ['/full/path/a', '/full/path/b']
+    end
+
+    it "should list paths from modules of included modules" do
+      mod = template(:c)
+      mod.send(:include, template(:d))
+      mod.send(:include, template(:a))
+      mod.full_paths.should == ['c', 'a', 'b', 'd'].map {|o| '/full/path/' + o }
+    end
+
+    it "should only list full paths of modules that respond to full_paths" do
+      mod = template(:d)
+      mod.send(:include, Enumerable)
+      mod.full_paths.should == ['/full/path/d']
+    end
+  end
+
+  describe '.load_setup_rb' do
+    it "should load setup.rb file for module" do
+      File.should_receive(:file?).with('/full/path/e/setup.rb').and_return(true)
+      File.should_receive(:read).with('/full/path/e/setup.rb').and_return('def success; end')
+      template(:e).new.should respond_to(:success)
+    end
+  end
+
+  describe '.T' do
+    it "should load template from absolute path" do
+      mod = template(:a)
+      Engine.should_receive(:template).with('other')
+      mod.T('other')
+    end
+  end
+
+  describe '.find_file' do
+    it "should find file in module's full_path" do
+      File.should_receive(:file?).with('/full/path/a/basename').and_return(false)
+      File.should_receive(:file?).with('/full/path/b/basename').and_return(true)
+      template(:a).find_file('basename').should == '/full/path/b/basename'
+    end
+
+    it "should return nil if no file is found" do
+      File.should_receive(:file?).with('/full/path/a/basename').and_return(false)
+      File.should_receive(:file?).with('/full/path/b/basename').and_return(false)
+      template(:a).find_file('basename').should be_nil
+    end
+  end
+
+  describe '.find_nth_file' do
+    it "should find 2nd existing file in template paths" do
+      File.should_receive(:file?).with('/full/path/a/basename').and_return(true)
+      File.should_receive(:file?).with('/full/path/b/basename').and_return(true)
+      template(:a).find_nth_file('basename', 2).should == '/full/path/b/basename'
+    end
+
+    it "should return nil if no file is found" do
+      File.should_receive(:file?).with('/full/path/a/basename').and_return(true)
+      File.should_receive(:file?).with('/full/path/b/basename').and_return(true)
+      template(:a).find_nth_file('basename', 3).should be_nil
+    end
+  end
+
+  describe '.extra_includes' do
+    it "should be included when a module is initialized" do
+      module MyModule; end
+      Template.extra_includes << MyModule
+      template(:e).new.should be_kind_of(MyModule)
+    end
+
+    it "should support lambdas in list" do
+      module MyModule2; end
+      Template.extra_includes << lambda {|opts| MyModule2 if opts.format == :html }
+      template(:f).new(:format => :html).should be_kind_of(MyModule2)
+      metaclass = (class << template(:g).new(:format => :text); self end)
+      metaclass.ancestors.should_not include(MyModule2)
+    end
+  end
+
+  describe '.is_a?' do
+    it "should be kind of Template" do
+      template(:e).is_a?(Template).should == true
+    end
+  end
+
+  describe '#T' do
+    it "should delegate to class method" do
+      template(:e).should_receive(:T).with('test')
+      template(:e).new.T('test')
+    end
+  end
+
+  describe '#init' do
+    it "should be called during initialization" do
+      module YARD::Templates::Engine::Template__full_path_e
+        def init; sections 1, 2, 3 end
+      end
+      template(:e).new.sections.should == Section.new(nil, 1, 2, 3)
+    end
+  end
+
+  describe '#file' do
+    it "should read the file if it exists" do
+      File.should_receive(:file?).with('/full/path/e/abc').and_return(true)
+      IO.should_receive(:read).with('/full/path/e/abc').and_return('hello world')
+      template(:e).new.file('abc').should == 'hello world'
+    end
+
+    it "should raise ArgumentError if the file does not exist" do
+      File.should_receive(:file?).with('/full/path/e/abc').and_return(false)
+      lambda { template(:e).new.file('abc') }.should raise_error(ArgumentError)
+    end
+
+    it "should replace {{{__super__}}} with inherited template contents if allow_inherited=true" do
+      File.should_receive(:file?).with('/full/path/a/abc').twice.and_return(true)
+      File.should_receive(:file?).with('/full/path/b/abc').and_return(true)
+      IO.should_receive(:read).with('/full/path/a/abc').and_return('foo {{{__super__}}}')
+      IO.should_receive(:read).with('/full/path/b/abc').and_return('bar')
+      template(:a).new.file('abc', true).should == "foo bar"
+    end
+
+    it "should not replace {{{__super__}}} with inherited template contents if allow_inherited=false" do
+      File.should_receive(:file?).with('/full/path/a/abc').and_return(true)
+      IO.should_receive(:read).with('/full/path/a/abc').and_return('foo {{{__super__}}}')
+      template(:a).new.file('abc').should == "foo {{{__super__}}}"
+    end
+  end
+
+  describe '#superb' do
+    it "should return the inherited erb template contents" do
+      File.should_receive(:file?).with('/full/path/a/test.erb').and_return(true)
+      File.should_receive(:file?).with('/full/path/b/test.erb').and_return(true)
+      IO.should_receive(:read).with('/full/path/b/test.erb').and_return('bar')
+      template = template(:a).new
+      template.section = :test
+      template.superb.should == "bar"
+    end
+
+    it "should work inside an erb template" do
+      File.should_receive(:file?).with('/full/path/a/test.erb').twice.and_return(true)
+      File.should_receive(:file?).with('/full/path/b/test.erb').and_return(true)
+      IO.should_receive(:read).with('/full/path/a/test.erb').and_return('foo<%= superb %>!')
+      IO.should_receive(:read).with('/full/path/b/test.erb').and_return('bar')
+      template = template(:a).new
+      template.section = :test
+      template.erb(:test).should == "foobar!"
+    end
+  end
+
+  describe '#sections' do
+    it "should allow sections to be set if arguments are provided" do
+      mod = template(:e).new
+      mod.sections 1, 2, [3]
+      mod.sections.should == Section.new(nil, 1, 2, [3])
+    end
+  end
+
+  describe '#run' do
+    it "should render all sections" do
+      mod = template(:e).new
+      mod.should_receive(:render_section).with(Section.new(:a)).and_return('a')
+      mod.should_receive(:render_section).with(Section.new(:b)).and_return('b')
+      mod.should_receive(:render_section).with(Section.new(:c)).and_return('c')
+      mod.sections :a, :b, :c
+      mod.run.should == 'abc'
+    end
+
+    it "should render all sections with options" do
+      mod = template(:e).new
+      mod.should_receive(:render_section).with(Section.new(:a)).and_return('a')
+      mod.should_receive(:add_options).with(:a => 1).and_yield
+      mod.sections :a
+      mod.run(:a => 1).should == 'a'
+    end
+
+    it "should run section list if provided" do
+      mod = template(:e).new
+      mod.should_receive(:render_section).with(Section.new(:q))
+      mod.should_receive(:render_section).with(Section.new(:x))
+      mod.run({}, [:q, :x])
+    end
+
+    it "should accept a nil section as empty string" do
+      mod = template(:e).new
+      mod.should_receive(:render_section).with(Section.new(:a))
+      mod.sections :a
+      mod.run.should == ""
+    end
+  end
+
+  describe '#add_options' do
+    it "should set instance variables in addition to options" do
+      mod = template(:f).new
+      mod.send(:add_options, {:a => 1, :b => 2})
+      mod.options.should == {:a => 1, :b => 2}
+      mod.instance_variable_get("@a").should == 1
+      mod.instance_variable_get("@b").should == 2
+    end
+
+    it "should set instance variables and options only for the block" do
+      mod = template(:f).new
+      mod.send(:add_options, {:a => 100, :b => 200}) do
+        mod.options.should == {:a => 100, :b => 200}
+      end
+      mod.options.should_not == {:a => 100, :b => 200}
+    end
+  end
+
+  describe '#render_section' do
+    it "should call method if method exists by section name as Symbol" do
+      mod = template(:f).new
+      mod.should_receive(:respond_to?).with(:a).and_return(true)
+      mod.should_receive(:respond_to?).with('a').and_return(true)
+      mod.should_receive(:send).with(:a).and_return('a')
+      mod.should_receive(:send).with('a').and_return('a')
+      mod.run({}, [:a, 'a']).should == 'aa'
+    end
+
+    it "should call erb if no method exists by section name" do
+      mod = template(:f).new
+      mod.should_receive(:respond_to?).with(:a).and_return(false)
+      mod.should_receive(:respond_to?).with('a').and_return(false)
+      mod.should_receive(:erb).with(:a).and_return('a')
+      mod.should_receive(:erb).with('a').and_return('a')
+      mod.run({}, [:a, 'a']).should == 'aa'
+    end
+
+    it "should run a template if section is one" do
+      mod2 = template(:g)
+      mod2.should_receive(:run)
+      mod = template(:f).new
+      mod.sections mod2
+      mod.run
+    end
+
+    it "should run a template instance if section is one" do
+      mod2 = template(:g).new
+      mod2.should_receive(:run)
+      mod = template(:f).new
+      mod.sections mod2
+      mod.run
+    end
+  end
+
+  describe '#yield' do
+    it "should yield a subsection" do
+      mod = template(:e).new
+      mod.sections :a, [:b, :c]
+      class << mod
+        def a; "(" + yield + ")" end
+        def b; "b" end
+        def c; "c" end
+      end
+
+      mod.run.should == "(b)"
+    end
+
+    it "should yield a subsection within a yielded subsection" do
+      mod = template(:e).new
+      mod.sections :a, [:b, [:c]]
+      class << mod
+        def a; "(" + yield + ")" end
+        def b; yield end
+        def c; "c" end
+      end
+
+      mod.run.should == "(c)"
+    end
+
+    it "should support arbitrary nesting" do
+      mod = template(:e).new
+      mod.sections :a, [:b, [:c, [:d, [:e]]]]
+      class << mod
+        def a; "(" + yield + ")" end
+        def b; yield end
+        def c; yield end
+        def d; yield end
+        def e; "e" end
+      end
+
+      mod.run.should == "(e)"
+    end
+
+    it "should yield first two elements if yield is called twice" do
+      mod = template(:e).new
+      mod.sections :a, [:b, :c, :d]
+      class << mod
+        def a; "(" + yield + yield + ")" end
+        def b; 'b' end
+        def c; "c" end
+      end
+
+      mod.run.should == "(bc)"
+    end
+
+    it "should ignore any subsections inside subsection yields" do
+      mod = template(:e).new
+      mod.sections :a, [:b, [:c], :d]
+      class << mod
+        def a; "(" + yield + yield + ")" end
+        def b; 'b' end
+        def d; "d" end
+      end
+
+      mod.run.should == "(bd)"
+    end
+
+    it "should allow extra options passed via yield" do
+      mod = template(:e).new
+      mod.sections :a, [:b]
+      class << mod
+        def a; "(" + yield(:x => "a") + ")" end
+        def b; options.x + @x end
+      end
+
+      mod.run.should == "(aa)"
+    end
+  end
+
+  describe '#yieldall' do
+    it "should yield all subsections" do
+      mod = template(:e).new
+      mod.sections :a, [:b, [:d, [:e]], :c]
+      class << mod
+        def a; "(" + yieldall + ")" end
+        def b; "b" + yieldall end
+        def c; "c" end
+        def d; 'd' + yieldall end
+        def e; 'e' end
+      end
+
+      mod.run.should == "(bdec)"
+    end
+
+    it "should yield options to all subsections" do
+      mod = template(:e).new
+      mod.sections :a, [:b, :c]
+      class << mod
+        def a; "(" + yieldall(:x => "2") + ")" end
+        def b; @x end
+        def c; @x end
+      end
+      mod.run.should == "(22)"
+    end
+
+    it "should yield all subsections more than once" do
+      mod = template(:e).new
+      mod.sections :a, [:b]
+      class << mod
+        def a; "(" + yieldall + yieldall + ")" end
+        def b; "b" end
+      end
+
+      mod.run.should == "(bb)"
+    end
+
+    it "should not yield if no yieldall is called" do
+      mod = template(:e).new
+      mod.sections :a, [:b]
+      class << mod
+        def a; "()" end
+        def b; "b" end
+      end
+
+      mod.run.should == "()"
+    end
+  end
+end

data/spec/verifier_spec.rb

@@ -0,0 +1,106 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::Verifier do
+  describe '#parse_expressions' do
+    it "should create #__execute method" do
+      v = Verifier.new("expr1")
+      v.should respond_to(:__execute)
+    end
+
+    it "should parse @tagname into tag('tagname')" do
+      obj = mock(:object)
+      obj.should_receive(:tag).with('return')
+      Verifier.new('@return').call(obj)
+    end
+
+    it "should parse @@tagname into object.tags('tagname')" do
+      obj = mock(:object)
+      obj.should_receive(:tags).with('return')
+      Verifier.new('@@return').call(obj)
+    end
+
+    it "should allow namespaced tag using @{} syntax" do
+      obj = mock(:object)
+      obj.should_receive(:tag).with('yard.return')
+      Verifier.new('@{yard.return}').call(obj)
+    end
+
+    it "should allow namespaced tags using @{} syntax" do
+      obj = mock(:object)
+      obj.should_receive(:tags).with('yard.return')
+      Verifier.new('@@{yard.return}').call(obj)
+    end
+
+    it "should call methods on tag object" do
+      obj = mock(:object)
+      obj2 = mock(:tag)
+      obj.should_receive(:tag).with('return').and_return obj2
+      obj2.should_receive(:foo)
+      Verifier.new('@return.foo').call(obj)
+    end
+
+    it "should send any missing methods to object" do
+      obj = mock(:object)
+      obj.should_receive(:has_tag?).with('return')
+      Verifier.new('has_tag?("return")').call(obj)
+    end
+
+    it "should allow multiple expressions" do
+      obj = mock(:object)
+      obj.should_receive(:tag).with('return').and_return(true)
+      obj.should_receive(:tag).with('param').and_return(false)
+      Verifier.new('@return', '@param').call(obj).should == false
+    end
+  end
+
+  describe '#o' do
+    it "should alias object to o" do
+      obj = mock(:object)
+      obj.should_receive(:a).ordered
+      Verifier.new('o.a').call(obj)
+    end
+  end
+
+  describe '#call' do
+    it "should mock a nonexistent tag so that exceptions are not raised" do
+      obj = mock(:object)
+      obj.should_receive(:tag).and_return(nil)
+      Verifier.new('@return.text').call(obj).should == false
+    end
+
+    it "should not fail if no expressions were added" do
+      lambda { Verifier.new.call(nil) }.should_not raise_error
+    end
+
+    it "should always ignore proxy objects and return true" do
+      v = Verifier.new('tag(:x)')
+      lambda { v.call(P('foo')).should == true }.should_not raise_error
+    end
+  end
+
+  describe '#expressions' do
+    it "should maintain a list of all unparsed expressions" do
+      Verifier.new('@return.text', '@private').expressions.should == ['@return.text', '@private']
+    end
+  end
+
+  describe '#expressions=' do
+    it "should recompile expressions when attribute is modified" do
+      obj = mock(:object)
+      obj.should_receive(:tag).with('return')
+      v = Verifier.new
+      v.expressions = ['@return']
+      v.call(obj)
+    end
+  end
+
+  describe '#add_expressions' do
+    it "should add new expressions and recompile" do
+      obj = mock(:object)
+      obj.should_receive(:tag).with('return')
+      v = Verifier.new
+      v.add_expressions '@return'
+      v.call(obj)
+    end
+  end
+end

data/templates/default/class/dot/setup.rb

@@ -0,0 +1,6 @@
+include T('default/module/dot')
+
+def init
+  super
+  sections.push :superklass
+end

data/templates/default/class/dot/superklass.erb

@@ -0,0 +1,3 @@
+<% if object.superclass.path != "Object" && object.superclass.path != "BasicObject" %>
+  <%= format_path object %> -> <%= format_path object.superclass %>;
+<% end %>

data/templates/default/class/html/constructor_details.erb

@@ -0,0 +1,8 @@
+<div id="constructor_details" class="method_details_list">
+  <h2>Constructor Details</h2>
+  <% if @ctor.namespace != object %>
+    <p class="notice">This class inherits a constructor from <%= linkify @ctor, @ctor.namespace.path %></p>
+  <% else %>
+    <%= yieldall :object => @ctor, :index => 0 %>
+  <% end %>
+</div>

data/templates/default/class/html/setup.rb

@@ -0,0 +1 @@
+include T('default/module/html')

data/templates/default/class/html/subclasses.erb

@@ -0,0 +1,4 @@
+<div id="subclasses">
+  <h2>Direct Known Subclasses</h2>
+  <p class="children"><%= @subclasses.map {|name, child| linkify(child, name) }.join(", ") %></p>
+</div>

data/templates/default/class/setup.rb

@@ -0,0 +1,36 @@
+include T('default/module')
+
+def init
+  super
+  sections.place(:subclasses).before(:children)
+  sections.place(:constructor_details, [T('method_details')]).before(:methodmissing)
+end
+
+def constructor_details
+  ctors = object.meths(:inherited => true, :included => true)
+  return unless @ctor = ctors.find {|o| o.constructor? }
+  return if prune_method_listing([@ctor]).empty?
+  erb(:constructor_details)
+end
+
+def subclasses
+  return if object.path == "Object" # don't show subclasses for Object
+  unless globals.subclasses
+    globals.subclasses = {}
+    list = run_verifier Registry.all(:class)
+    list.each do |o|
+      (globals.subclasses[o.superclass.path] ||= []) << o if o.superclass
+    end
+  end
+
+  @subclasses = globals.subclasses[object.path]
+  return if @subclasses.nil? || @subclasses.empty?
+  @subclasses = @subclasses.sort_by {|o| o.path }.map do |child|
+    name = child.path
+    if object.namespace
+      name = object.relative_path(child)
+    end
+    [name, child]
+  end
+  erb(:subclasses)
+end

data/templates/default/class/text/setup.rb

@@ -0,0 +1,11 @@
+include T('default/module/text')
+
+def init
+  super
+  sections.place(:subclasses).before(:children)
+  sections.delete(:children)
+end
+
+def format_object_title(object)
+  "Class: #{object.title} < #{object.superclass.title}"
+end

data/templates/default/class/text/subclasses.erb

@@ -0,0 +1,5 @@
+Direct Known Subclasses:
+------------------------
+
+<%= indent(wrap(@subclasses.map {|name, child| name }.join(", "))) %>
+

data/templates/default/constant/text/header.erb

@@ -0,0 +1,11 @@
+<%= title_align_right format_object_title(object) %>
+
+
+<%= object.name %> = <%= object.value.size > 40 ? "\n\n" + indent(object.value) : object.value %>
+
+
+<%= hr %>
+
+<%= yieldall %>
+
+<%= hr %>

data/templates/default/constant/text/setup.rb

@@ -0,0 +1,3 @@
+def init
+  sections :header, [T('docstring')]
+end

data/templates/default/docstring/html/abstract.erb

@@ -0,0 +1,4 @@
+<div class="note abstract">
+  <strong>This <%= object.type %> is abstract.</strong>
+  <%= htmlify_line object.tag(:abstract).text %>
+</div>

data/templates/default/docstring/html/deprecated.erb

@@ -0,0 +1 @@
+<div class="note deprecated"><strong>Deprecated.</strong> <%= htmlify_line object.tag(:deprecated).text %></div>

data/templates/default/docstring/html/index.erb

@@ -0,0 +1,5 @@
+<div class="docstring">
+  <div class="discussion">
+    <%= yieldall %>
+  </div>
+</div>

data/templates/default/docstring/html/note.erb

@@ -0,0 +1,6 @@
+<% object.tags(:note).each do |tag| %>
+  <div class="note notetag">
+    <strong>Note:</strong>
+    <%= htmlify_line tag.text %>
+  </div>
+<% end %>

data/templates/default/docstring/html/private.erb

@@ -0,0 +1,4 @@
+<p class="note private">
+  <strong>This <%= object.type %> is part of a private API.</strong>
+  You should avoid using this <%= object.type %> if possible, as it may be removed or be changed in the future.
+</p>

data/templates/default/docstring/html/returns_void.erb

@@ -0,0 +1 @@
+<p class="note returns_void">This method returns an undefined value.</p>

data/templates/default/docstring/html/text.erb

@@ -0,0 +1 @@
+<%= htmlify(docstring_text) %>

data/templates/default/docstring/html/todo.erb

@@ -0,0 +1,6 @@
+<% object.tags(:todo).each do |tag| %>
+  <div class="note todo">
+    <strong>TODO:</strong>
+    <%= htmlify_line tag.text %>
+  </div>
+<% end %>