yard 0.2.2 → 0.2.3

data/spec/handlers/method_condition_handler_spec.rb

@@ -0,0 +1,14 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}MethodConditionHandler" do
+  before { parse_file :method_condition_handler_001, __FILE__ }
+  
+  it "should not parse regular if blocks in methods" do
+    Registry.at('#b').should be_nil
+  end
+  
+  it "should parse if/unless blocks in the form X if COND" do
+    Registry.at('#c').should_not be_nil
+    Registry.at('#d').should_not be_nil
+  end
+end

data/spec/handlers/method_handler_spec.rb

@@ -1,6 +1,6 @@
 require File.dirname(__FILE__) + '/spec_helper'
 
-describe YARD::Handlers::MethodHandler do
+describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}MethodHandler" do
   before do
     log.enter_level(Logger::ERROR) do
       parse_file :method_handler_001, __FILE__ 
@@ -12,11 +12,11 @@ describe YARD::Handlers::MethodHandler do
   end
   
   it "should parse/add class methods (self.method2)" do
-    P(:Foo).meths.should include(P("Foo::method2"))
+    P(:Foo).meths.should include(P("Foo.method2"))
   end
   
-  it "should parse/add class methods from other namespaces (String::hello)" do
-    P("String::hello").should_not be_nil
+  it "should parse/add class methods from other namespaces (String.hello)" do
+    P("String.hello").should be_instance_of(CodeObjects::MethodObject)
   end
   
   it "should allow punctuation in method names ([], ?, =~, <<, etc.)" do
@@ -32,4 +32,37 @@ describe YARD::Handlers::MethodHandler do
   it "should show that a method is explicitly defined (if it was originally defined implicitly by attribute)" do
     P('Foo#method1').is_explicit?.should == true
   end
-end
+  
+  it "should handle parameters" do
+    P('Foo#[]').parameters.should == [['key', "'default'"]]
+    P('Foo#/').parameters.should == [['x', "File.new('x', 'w')"], ['y', '2']]
+  end
+  
+  it "should handle opts = {} as parameter" do
+    P('Foo#optsmeth').parameters.should == [['x', nil], ['opts', '{}']]
+  end
+
+  it "should handle &block as parameter" do
+    P('Foo#blockmeth').parameters.should == [['x', nil], ['&block', nil]]
+  end
+
+  it "should handle overloads" do
+    meth = P('Foo#foo')
+
+    o1 = meth.tags(:overload).first
+    o1.name.should == :foo
+    o1.parameters.should == [[:a, nil], [:b, "1"]]
+    o1.tag(:return).type.should == "String"
+
+    o2 = meth.tags(:overload)[1]
+    o2.name.should == :foo
+    o2.parameters.should == [[:b, nil], [:c, nil]]
+    o2.tag(:return).type.should == "Fixnum"
+
+    o3 = meth.tags(:overload)[2]
+    o3.name.should == :foo
+    o3.parameters.should == [[:d, nil], [:e, nil]]
+    o3.docstring.should be_empty
+    o3.docstring.should be_blank
+  end
+end

data/spec/handlers/mixin_handler_spec.rb

@@ -1,18 +1,22 @@
 require File.dirname(__FILE__) + '/spec_helper'
 
-describe YARD::Handlers::MixinHandler do
+describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}MixinHandler" do
   before { parse_file :mixin_handler_001, __FILE__ }
   
   it "should handle includes from classes or modules" do
-    Registry.at(:X).mixins.should include(P(:A))
-    Registry.at(:Y).mixins.should include(P(:A))
+    Registry.at(:X).instance_mixins.should include(P(:A))
+    Registry.at(:Y).instance_mixins.should include(P(:A))
+  end
+
+  it "should handle includes in class << self" do
+    Registry.at(:Y).class_mixins.should include(P(:A))
   end
   
   it "should handle includes for complex namespaces" do
   end
   
   it "should handle includes for modules that don't yet exist" do
-    Registry.at(:X).mixins.should include(P(nil, :NOTEXIST))
+    Registry.at(:X).instance_mixins.should include(P(nil, :NOTEXIST))
   end
   
   it "should set the type of non-existing modules to :module" do
@@ -24,7 +28,11 @@ describe YARD::Handlers::MixinHandler do
   end
   
   it "should handle complex include statements" do
-    P(:Y).mixins.should include(P('B::C'))
-    P(:Y).mixins.should include(P(:B))
+    P(:Y).instance_mixins.should include(P('B::C'))
+    P(:Y).instance_mixins.should include(P(:B))
+  end
+  
+  it "should treat a mixed in Constant by taking its value as the real object name" do
+    P(:Y).instance_mixins.should include(Registry.at('B::D'))
   end
-end
+end

data/spec/handlers/module_handler_spec.rb

@@ -1,6 +1,6 @@
 require File.dirname(__FILE__) + '/spec_helper'
 
-describe YARD::Handlers::ModuleHandler do
+describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}ModuleHandler" do
   before do
     Registry.clear 
     parse_file :module_handler_001, __FILE__
@@ -22,4 +22,8 @@ describe YARD::Handlers::ModuleHandler do
   it "should handle complex module names" do
     Registry.at("A::B").should_not == nil
   end
+  
+  it "should handle modules in the form ::ModName" do
+    Registry.at("Kernel").should_not be_nil
+  end
 end

data/spec/handlers/processor_spec.rb

@@ -0,0 +1,19 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::Handlers::Processor do
+  before do
+    @proc = Handlers::Processor.new
+  end
+  
+  it "should start with public visibility" do
+    @proc.visibility.should == :public
+  end
+  
+  it "should start in instance scope" do
+    @proc.scope.should == :instance
+  end
+  
+  it "should start in root namespace" do
+    @proc.namespace.should == Registry.root
+  end
+end

data/spec/handlers/ruby/base_spec.rb

@@ -0,0 +1,90 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe YARD::Handlers::Ruby::Base, '#valid_handler?' do
+  include YARD::Parser::Ruby; AstNode
+
+  before do
+    Handlers::Ruby::Base.stub!(:inherited)
+    @processor = Handlers::Processor.new(nil, false, :ruby)
+  end
+  
+  def valid(handler, stmt)
+    @processor.find_handlers(stmt).should include(handler)
+  end
+  
+  def invalid(handler, stmt)
+    @processor.find_handlers(stmt).should_not include(handler)
+  end
+
+  it "should only handle Handlers inherited from Ruby::Base class" do
+    class IgnoredHandler < Handlers::Base
+      handles :list
+    end
+    class NotIgnoredHandler < Handlers::Ruby::Base
+      handles :list
+    end
+    Handlers::Base.stub!(:subclasses).and_return [IgnoredHandler, NotIgnoredHandler]
+    @processor.find_handlers(s()).should == [NotIgnoredHandler]
+  end
+
+  it "should handle string input (matches AstNode#source)" do
+    class StringHandler < Handlers::Ruby::Base
+      handles "x"
+    end
+    Handlers::Base.stub!(:subclasses).and_return [StringHandler]
+    ast = RubyParser.parse("if x == 2 then true end").ast
+    valid StringHandler, ast[0][0][0]
+    invalid StringHandler, ast[0][1]
+  end
+  
+  it "should handle symbol input (matches AstNode#type)" do
+    class SymbolHandler < Handlers::Ruby::Base
+      handles :myNodeType
+    end
+    Handlers::Base.stub!(:subclasses).and_return [SymbolHandler]
+    valid SymbolHandler, s(:myNodeType, s(1, 2, 3))
+    invalid SymbolHandler, s(:NOTmyNodeType, s(1, 2, 3))
+  end
+
+  it "should handle regex input (matches AstNode#source)" do
+    class RegexHandler < Handlers::Ruby::Base
+      handles %r{^if x ==}
+    end
+    Handlers::Base.stub!(:subclasses).and_return [RegexHandler]
+    ast = RubyParser.parse("if x == 2 then true end").ast
+    valid RegexHandler, ast
+    invalid RegexHandler, ast[0][1]
+  end
+
+  it "should handle AstNode input (matches AST literally)" do
+    class ASTHandler < Handlers::Ruby::Base
+      handles s(:var_ref, s(:ident, "hello_world"))
+    end
+    Handlers::Base.stub!(:subclasses).and_return [ASTHandler]
+    valid ASTHandler, s(:var_ref, s(:ident, "hello_world"))
+    invalid ASTHandler, s(:var_ref, s(:ident, "NOTHELLOWORLD"))
+  end
+  
+  it "should handle #method_call(:methname) on a valid AST" do
+    class MethCallHandler < Handlers::Ruby::Base
+      handles method_call(:meth)
+    end
+    Handlers::Base.stub!(:subclasses).and_return [MethCallHandler]
+    ast = RubyParser.parse(<<-"eof").ast
+      meth                   # 0
+      meth()                 # 1
+      meth(1,2,3)            # 2
+      meth 1,2,3             # 3
+      NotMeth.meth           # 4
+      NotMeth.meth { }       # 5
+      NotMeth.meth do end    # 6
+      NotMeth.meth 1, 2, 3   # 7
+      NotMeth.meth(1, 2, 3)  # 8
+      NotMeth                # 9
+    eof
+    (0..8).each do |i|
+      valid MethCallHandler, ast[i]
+    end
+    invalid MethCallHandler, ast[9]
+  end
+end if RUBY19

data/spec/handlers/ruby/legacy/base_spec.rb

@@ -0,0 +1,53 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+
+include Parser::Ruby::Legacy
+
+describe YARD::Handlers::Ruby::Legacy::Base, "#handles and inheritance" do
+  before do
+    Handlers::Ruby::Legacy::Base.stub!(:inherited)
+    Handlers::Ruby::Legacy::MixinHandler.stub!(:inherited) # fixes a Ruby1.9 issue
+    @processor = Handlers::Processor.new(nil, false, :ruby18)
+  end
+  
+  def stmt(string)
+    Statement.new(TokenList.new(string))
+  end
+  
+  it "should only handle Handlers inherited from Ruby::Legacy::Base class" do
+    class IgnoredHandler < Handlers::Base
+      handles "hello"
+    end
+    class NotIgnoredHandler < Handlers::Ruby::Legacy::Base
+      handles "hello"
+    end
+    Handlers::Base.stub!(:subclasses).and_return [IgnoredHandler, NotIgnoredHandler]
+    @processor.find_handlers(stmt("hello world")).should == [NotIgnoredHandler]
+  end
+
+  it "should handle a string input" do
+    class TestStringHandler < Handlers::Ruby::Legacy::Base
+      handles "hello"
+    end
+
+    TestStringHandler.handles?(stmt("hello world")).should be_true
+    TestStringHandler.handles?(stmt("nothello world")).should be_false
+  end
+
+  it "should handle regex input" do
+    class TestRegexHandler < Handlers::Ruby::Legacy::Base
+      handles /^nothello$/
+    end
+
+    TestRegexHandler.handles?(stmt("nothello")).should be_true
+    TestRegexHandler.handles?(stmt("not hello hello")).should be_false
+  end
+
+  it "should handle token input" do
+    class TestTokenHandler < Handlers::Ruby::Legacy::Base
+      handles TkMODULE
+    end
+
+    TestTokenHandler.handles?(stmt("module")).should be_true
+    TestTokenHandler.handles?(stmt("if")).should be_false
+  end
+end

data/spec/handlers/spec_helper.rb

@@ -1,21 +1,27 @@
 require File.join(File.dirname(__FILE__), "..", "spec_helper")
+require 'stringio'
 
 include Handlers
 
 def undoc_error(code)
-  mock = mock("parser")
-  mock.stub!(:namespace).and_return(Registry.root)
-  mock.stub!(:namespace=).and_return nil
-  mock.stub!(:owner).and_return(Registry.root)
-  mock.stub!(:owner=).and_return nil
-  mock.stub!(:scope).and_return(:instance)
-  mock.stub!(:scope=).and_return nil
-  mock.stub!(:visibility).and_return(:public)
-  mock.stub!(:visibility=).and_return nil
-  mock.stub!(:file).and_return('<STDIN>')
-  mock.stub!(:parse).and_return nil
-  mock.stub!(:load_order_errors).and_return false
-  
-  c = self.class.described_type.new(mock, Parser::StatementList.new(code).first)
-  lambda { c.process }.should raise_error(UndocumentableError)
-end
+  lambda { StubbedSourceParser.parse_string(code) }.should raise_error(Parser::UndocumentableError)
+end
+
+class StubbedProcessor < Processor
+  def process(statements)
+    statements.each_with_index do |stmt, index|
+      find_handlers(stmt).each do |handler| 
+        handler.new(self, stmt).process
+      end
+    end
+  end
+end
+
+class StubbedSourceParser < Parser::SourceParser
+  self.parser_type = :ruby
+  def post_process
+    post = StubbedProcessor.new(@file, @load_order_errors, @parser_type)
+    post.process(@parser.enumerator)
+  end
+end
+  

data/spec/handlers/visibility_handler_spec.rb

@@ -1,6 +1,6 @@
 require File.dirname(__FILE__) + '/spec_helper'
 
-describe YARD::Handlers::VisibilityHandler do
+describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}VisibilityHandler" do
   before { parse_file :visibility_handler_001, __FILE__ }
   
   it "should be able to set visibility to public" do
@@ -17,8 +17,8 @@ describe YARD::Handlers::VisibilityHandler do
   end
   
   it "should support parameters and only set visibility on those methods" do
-    Registry['Testing#notpriv'].visibility.should == :public
-    Registry['Testing#notpriv2'].visibility.should == :public
-    Registry['Testing#notpriv?'].visibility.should == :public
+    Registry['Testing#notpriv'].visibility.should == :protected
+    Registry['Testing#notpriv2'].visibility.should == :protected
+    Registry['Testing#notpriv?'].visibility.should == :protected
   end
 end

data/spec/handlers/yield_handler_spec.rb

@@ -1,6 +1,6 @@
 require File.dirname(__FILE__) + '/spec_helper'
 
-describe YARD::Handlers::YieldHandler do
+describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}YieldHandler" do
   before { parse_file :yield_handler_001, __FILE__ }
   
   it "should only parse yield blocks in methods" do

data/spec/parser/ruby/ast_node_spec.rb

@@ -0,0 +1,15 @@
+require File.join(File.dirname(__FILE__), '..', '..', 'spec_helper')
+
+include YARD::Parser::Ruby
+
+describe YARD::Parser::Ruby::AstNode, "#jump" do
+  it "should jump to the first specific inner node if found" do
+    ast = s(:paren, s(:paren, s(:params, s(s(:ident, "hi"), s(:ident, "bye")))))
+    ast.jump(:params)[0][0].type.should equal(:ident)
+  end
+  
+  it "should return the original ast if no inner node is found" do
+    ast = s(:paren, s(:list, s(:list, s(s(:ident, "hi"), s(:ident, "bye")))))
+    ast.jump(:params).object_id.should == ast.object_id
+  end
+end if RUBY19

data/spec/parser/ruby/legacy/statement_list_spec.rb

@@ -0,0 +1,145 @@
+require File.join(File.dirname(__FILE__), '..', '..', '..', 'spec_helper')
+
+describe YARD::Parser::Ruby::Legacy::StatementList do
+  def stmt(code) YARD::Parser::Ruby::Legacy::StatementList.new(code).first end
+
+  it "should parse dangling block expressions" do
+    s = stmt <<-eof
+      if
+          foo
+        puts 'hi'
+      end
+eof
+
+    s.tokens.to_s.should == "if          foo"
+    s.block.to_s.should == "\n        puts 'hi'\n      end\n"
+
+    s = stmt <<-eof
+      if foo ||
+          bar
+        puts 'hi'
+      end
+eof
+
+    s.tokens.to_s.should == "if foo ||          bar"
+    s.block.to_s.should == "\n        puts 'hi'\n      end\n"
+  end
+
+  it "should allow semicolons within parentheses" do
+    s = stmt "(foo; bar)"
+
+    s.tokens.to_s.should == "(foo; bar)"
+    s.block.to_s.should == ""
+  end
+
+  it "should allow block statements to be used as part of other block statements" do
+    s = stmt "while (foo; bar); foo = 12; end"
+
+    s.tokens.to_s.should == "while (foo; bar)"
+    s.block.to_s.should == " foo = 12; end\n"
+  end
+
+  it "should allow continued processing after a block" do
+    s = stmt "if foo; end.stuff"
+    s.tokens.to_s.should == "if foo"
+    s.block.to_s.should == " end.stuff\n"
+
+    s = stmt "if foo; end[stuff]"
+    s.tokens.to_s.should == "if foo"
+    s.block.to_s.should == " end[stuff]\n"
+
+    s = stmt "if foo; end.map do; 123; end"
+    s.tokens.to_s.should == "if foo"
+    s.block.to_s.should == " end.map do; 123; end\n"
+  end
+
+  it "should parse default arguments" do
+    s = stmt "def foo(bar, baz = 1, bang = 2); bar; end"
+    s.tokens.to_s.should == "def foo(bar, baz = 1, bang = 2)"
+    s.block.to_s.should == " bar; end\n"
+
+    s = stmt "def foo bar, baz = 1, bang = 2; bar; end"
+    s.tokens.to_s.should == "def foo bar, baz = 1, bang = 2"
+    s.block.to_s.should == " bar; end\n"
+
+    s = stmt "def foo bar , baz = 1 , bang = 2; bar; end"
+    s.tokens.to_s.should == "def foo bar , baz = 1 , bang = 2"
+    s.block.to_s.should == " bar; end\n"
+  end
+
+  it "should parse complex default arguments" do
+    s = stmt "def foo(bar, baz = File.new(1, 2), bang = 3); bar; end"
+    s.tokens.to_s.should == "def foo(bar, baz = File.new(1, 2), bang = 3)"
+    s.block.to_s.should == " bar; end\n"
+
+    s = stmt "def foo bar, baz = File.new(1, 2), bang = 3; bar; end"
+    s.tokens.to_s.should == "def foo bar, baz = File.new(1, 2), bang = 3"
+    s.block.to_s.should == " bar; end\n"
+
+    s = stmt "def foo bar , baz = File.new(1, 2) , bang = 3; bar; end"
+    s.tokens.to_s.should == "def foo bar , baz = File.new(1, 2) , bang = 3"
+    s.block.to_s.should == " bar; end\n"
+  end
+
+  it "should parse blocks with do/end" do
+    s = stmt <<-eof
+      foo do
+        puts 'hi'
+      end
+    eof
+
+    s.tokens.to_s.should == "foo "
+    s.block.to_s.should == "do\n        puts 'hi'\n      end\n"
+  end
+  
+  it "should parse blocks with {}" do
+    s = stmt "x { y }"
+    s.tokens.to_s.should == "x "
+    s.block.to_s.should == "{ y }\n"
+
+    s = stmt "x() { y }"
+    s.tokens.to_s.should == "x() "
+    s.block.to_s.should == "{ y }\n"
+  end
+  
+  it "should parse blocks with begin/end" do
+    s = stmt "begin xyz end"
+    s.tokens.to_s.should == ""
+    s.block.to_s.should == "begin xyz end\n"
+  end
+  
+  it "should parse nested blocks" do
+    s = stmt "foo(:x) { baz(:y) { skippy } }"
+    
+    s.tokens.to_s.should == "foo(:x) "
+    s.block.to_s.should == "{ baz(:y) { skippy } }\n"
+  end
+
+  it "should not parse hashes as blocks" do
+    s = stmt "x({})"
+    s.tokens.to_s.should == "x({})"
+    s.block.to_s.should == ""
+
+    s = stmt "x = {}"
+    s.tokens.to_s.should == "x = {}"
+    s.block.to_s.should == ""
+
+    s = stmt "x(y, {})"
+    s.tokens.to_s.should == "x(y, {})"
+    s.block.to_s.should == ""
+  end
+
+  it "should parse hashes in blocks with {}" do
+    s = stmt "x {x = {}}"
+
+    s.tokens.to_s.should == "x "
+    s.block.to_s.should == "{x = {}}\n"
+  end
+
+  it "should parse blocks with {} in hashes" do
+    s = stmt "[:foo, x {}]"
+
+    s.tokens.to_s.should == "[:foo, x {}]"
+    s.block.to_s.should == ""
+  end
+end