yard 0.2.3.5 → 0.4.0

data/spec/handlers/class_handler_spec.rb

@@ -106,4 +106,7 @@ describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}ClassHandler" do
     Registry.at(:RT).superclass.should == P('XX::RT')
   end
   
+  it "should not overwrite docstring with an empty one" do
+    Registry.at(:Zebra).docstring.should == "Docstring 2"
+  end
 end

data/spec/handlers/class_variable_handler_spec.rb

@@ -4,6 +4,8 @@ describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}ClassVariableHandler"
   before(:all) { parse_file :class_variable_handler_001, __FILE__ }
   
   it "should not parse class variables inside methods" do
-    Registry.at("A::B::@@somevar").source.should == "@@somevar = \"hello\""
+    obj = Registry.at("A::B::@@somevar")
+    obj.source.should == "@@somevar = \"hello\""
+    obj.value.should == '"hello"'
   end
 end

data/spec/handlers/constant_handler_spec.rb

@@ -10,4 +10,42 @@ describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}ConstantHandler" do
   it "should only parse valid constants" do
     Registry.at("A::B::notaconstant").should be_nil
   end
+  
+  it "should maintain newlines" do
+    Registry.at("A::B::MYCONSTANT").value.should == "A +\nB +\nC +\nD"
+  end
+  
+  it "should turn Const = Struct.new(:sym) into class Const with attr :sym" do
+    obj = Registry.at("MyClass")
+    obj.should be_kind_of(CodeObjects::ClassObject)
+    attrs = obj.attributes[:instance]
+    [:a, :b, :c].each do |key|
+      attrs.should have_key(key)
+      attrs[key][:read].should_not be_nil
+      attrs[key][:write].should_not be_nil
+    end
+  end
+
+  it "should turn Const = Struct.new('Name', :sym) into class Const with attr :sym" do
+    obj = Registry.at("NotMyClass")
+    obj.should be_kind_of(CodeObjects::ClassObject)
+    attrs = obj.attributes[:instance]
+    [:b, :c].each do |key|
+      attrs.should have_key(key)
+      attrs[key][:read].should_not be_nil
+      attrs[key][:write].should_not be_nil
+    end
+
+    Registry.at("NotMyClass2").should be_nil
+  end
+  
+  it "should turn Const = Struct.new into empty struct" do
+    obj = Registry.at("MyEmptyStruct")
+    obj.should_not be_nil
+    obj.attributes[:instance].should be_empty
+  end
+  
+  it "should raise undocumentable error in 1.9 parser for Struct.new assignment to non-const" do
+    undoc_error "nonconst = Struct.new"
+  end if RUBY19
 end

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

@@ -69,4 +69,17 @@ end
 
 class << Symbol
   alias toString to_s
-end
+end
+
+# Docstring
+class Zebra
+end
+
+# Docstring 2
+
+class Zebra
+end
+
+class Zebra
+end
+

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

@@ -1,6 +1,7 @@
 module A
   class B
     @@somevar = "hello"
+	@@somevar.value = "H"
 
     def method
       @@somevar = "don't document this"

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

@@ -6,5 +6,14 @@ module A
     def method
       SOMECONSTANT = "don't document this"
     end
+
+    MYCONSTANT = A +
+      B +
+      C +
+      D
   end
-end
+end
+
+MyClass = Struct.new(:a, :b, :c)
+NotMyClass = Struct.new("NotMyClass2", :b, :c)
+MyEmptyStruct = Struct.new

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

@@ -39,4 +39,9 @@ class Testing
   def mymethod8
     raise ExceptionClass.new('blah')
   end
+
+  def mymethod9
+    obj.raise IgnoreMe
+	obj.raise(IgnoreMe)
+  end
 end

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

@@ -1,4 +1,17 @@
 class Foo
+  class << self
+    def inherited; end
+    def included; end
+    # docstring
+    def extended; end
+    def method_added; end
+    def method_removed; end
+    def method_undefined; end
+  end
+
+  # A docstring but no return type
+  def initialize; end
+
   def ==(other)
     'hello' 
   end
@@ -14,6 +27,8 @@ class Foo
 
   # Docstring
   def String :: hello; "" end
+  
+  def self.new() end
 
   def [](key = 'default') puts key end
   def []=(key, value) end

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

@@ -18,3 +18,16 @@ module Y
 
   class << self; include A; end
 end
+
+module ABC
+  module FOO; end
+  module DEF
+    module FOO
+      include ABC::FOO
+    end
+    
+    module BAR
+      include ABC::BAR
+    end
+  end
+end  

data/spec/handlers/exception_handler_spec.rb

@@ -32,4 +32,8 @@ describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}ExceptionHandler" do
   it "should handle complex class names" do
     P('Testing#mymethod5').tag(:raise).types.should == ['YARD::Parser::UndocumentableError']
   end
+  
+  it "should ignore any raise calls on a receiver" do
+    P('Testing#mymethod9').tag(:raise).should be_nil
+  end
 end

data/spec/handlers/method_handler_spec.rb

@@ -25,6 +25,10 @@ describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}MethodHandler" do
     end
   end
   
+  it "should allow self.methname" do
+    Registry.at("Foo.new").should_not be_nil
+  end
+  
   it "should mark dynamic methods as such" do
     P('Foo#dynamic').dynamic?.should == true
   end
@@ -65,4 +69,22 @@ describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}MethodHandler" do
     o3.docstring.should be_empty
     o3.docstring.should be_blank
   end
+  
+  it "should set a return tag if not set on #initialize" do
+    meth = P('Foo#initialize')
+    
+    meth.should have_tag(:return)
+    meth.tag(:return).types.should == ["Foo"]
+    meth.tag(:return).text.should == "a new instance of +Foo+"
+  end
+  
+  %w(inherited included method_added method_removed method_undefined).each do |meth|
+    it "should set @private tag on #{meth} callback method if no docstring is set" do
+      P('Foo.' + meth).should have_tag(:private)
+    end
+  end
+  
+  it "should not set @private tag on extended callback method since docstring is set" do
+    P('Foo.extended').should_not have_tag(:private)
+  end
 end

data/spec/handlers/mixin_handler_spec.rb

@@ -12,9 +12,6 @@ describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}MixinHandler" 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).instance_mixins.should include(P(nil, :NOTEXIST))
   end
@@ -35,4 +32,9 @@ describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}MixinHandler" do
   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
+  
+  it "should avoid including self for unresolved mixins of the same name" do
+    P("ABC::DEF::FOO").mixins.should == [P("ABC::FOO")]
+    P("ABC::DEF::BAR").mixins.should == [P("ABC::BAR")]
+  end
 end

data/spec/handlers/yield_handler_spec.rb

@@ -9,7 +9,7 @@ describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}YieldHandler" do
   end
   
   it "should handle an empty yield statement" do
-    P('Testing#mymethod').tag(:yield).should_not be_nil
+    P('Testing#mymethod').tag(:yield).should be_nil
     P('Testing#mymethod').tag(:yieldparam).should be_nil
   end
   

data/spec/parser/ruby/ast_node_spec.rb

@@ -1,4 +1,6 @@
 require File.join(File.dirname(__FILE__), '..', '..', 'spec_helper')
+require 'pp'
+require 'stringio'
 
 include YARD::Parser::Ruby
 
@@ -15,5 +17,19 @@ if RUBY19
         ast.jump(:params).object_id.should == ast.object_id
       end
     end
+    
+    describe '#pretty_print' do
+      it "should show a list of nodes" do
+        obj = YARD::Parser::Ruby::RubyParser.parse("# x\nbye", "x").ast
+        out = StringIO.new
+        PP.pp(obj, out)
+        out.rewind
+        out.read.should == "s(s(:var_ref,\n" +
+          "      s(:ident, \"bye\", line: 2..2, source: 4..6),\n" +
+          "      docstring: \"x\",\n" +
+          "      line: 2..2,\n" +
+          "      source: 4..6))\n"
+      end
+    end
   end
 end

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

@@ -220,4 +220,40 @@ eof
     s.comments.should == ["comment"]
     s.comments_range.should == (1..1)
   end
+  
+  it "should only look up to two lines back for comments" do
+    s = stmt <<-eof
+      # comments
+      
+      # comments
+      
+      def method; end
+    eof
+    s.comments.should == ["comments"]
+    
+    s = stmt <<-eof
+      # comments
+      
+      
+      def method; end
+    eof
+    s.comments.should == nil
+
+    ss = stmts <<-eof
+      # comments
+      
+      
+      def method; end
+      
+      # hello
+      def method2; end
+    eof
+    ss[0].comments.should == nil
+    ss[1].comments.should == ['hello']
+  end
+  
+  it "should handle CRLF (Windows) newlines" do
+    s = stmts("require 'foo'\r\n\r\n# Test Test\r\n# \r\n# Example:\r\n#   example code\r\ndef test\r\nend\r\n")
+    s[1].comments.should == ['Test Test', '', 'Example:', '  example code']
+  end
 end

data/spec/parser/ruby/ruby_parser_spec.rb

@@ -6,6 +6,10 @@ if RUBY19
       YARD::Parser::Ruby::RubyParser.new(stmt, nil).parse.root.first
     end
     
+    def stmts(stmts)
+      YARD::Parser::Ruby::RubyParser.new(stmts, nil).parse.root
+    end
+    
     describe '#parse' do
       it "should get comment line numbers" do
         s = stmt <<-eof
@@ -49,6 +53,37 @@ if RUBY19
         s.comments_range.should == (1..1)
       end
       
+      it "should only look up to two lines back for comments" do
+        s = stmt <<-eof
+          # comments
+
+          # comments
+
+          def method; end
+        eof
+        s.comments.should == "comments"
+
+        s = stmt <<-eof
+          # comments
+
+
+          def method; end
+        eof
+        s.comments.should == nil
+
+        ss = stmts <<-eof
+          # comments
+
+
+          def method; end
+
+          # hello
+          def method2; end
+        eof
+        ss[0].comments.should == nil
+        ss[1].comments.should == 'hello'
+      end
+      
       it "should handle 1.9 lambda syntax with args" do
         src = "->(a,b,c=1,*args,&block) { hello_world }"
         stmt(src).source.should == src
@@ -90,6 +125,51 @@ if RUBY19
         ast[0].should == "a"
         ast.source.should == "a:"
       end
+      
+      it "should handle begin/rescue blocks" do
+        ast = stmt("begin; X; rescue => e; Y end").jump(:rescue)
+        ast.source.should == "rescue => e; Y end"
+
+        ast = stmt("begin; X; rescue A => e; Y end").jump(:rescue)
+        ast.source.should == "rescue A => e; Y end"
+
+        ast = stmt("begin; X; rescue A, B => e; Y end").jump(:rescue)
+        ast.source.should == "rescue A, B => e; Y end"
+      end
+      
+      it "should handle method rescue blocks" do
+        ast = stmt("def x; A; rescue Y; B end")
+        ast.source.should == "def x; A; rescue Y; B end"
+        ast.jump(:rescue).source.should == "rescue Y; B end"
+      end
+      
+      it "should handle defs with keywords as method name" do
+        ast = stmt("# docstring\nclass A;\ndef class; end\nend")
+        ast.jump(:class).docstring.should == "docstring"
+        ast.jump(:class).line_range.should == (2..4)
+      end
+      
+      it "should end source properly on array reference" do
+        ast = stmt("AS[0, 1 ]   ")
+        ast.source.should == 'AS[0, 1 ]'
+
+        ast = stmt("def x(a = S[1]) end").jump(:default_arg)
+        ast.source.should == 'a = S[1]'
+      end
+      
+      it "should end source properly on if/unless mod" do
+        %w(if unless while).each do |mod|
+          stmt("A=1 #{mod} true").source.should == "A=1 #{mod} true"
+        end
+      end
+      
+      it "should show proper source for assignment" do
+        stmt("A=1").jump(:assign).source.should == "A=1"
+      end
+      
+      it "should sho" do
+        p stmt("A = Struct.new :a, :b")[1].parameters
+      end
     end
   end
 end

data/spec/parser/source_parser_spec.rb

@@ -7,7 +7,7 @@ describe YARD::Parser::SourceParser do
   
   describe '#parse_string' do
     it "should parse basic Ruby code" do
-      Parser::SourceParser.parse_string(<<-eof)
+      YARD.parse_string(<<-eof)
         module Hello
           class Hi
             # Docstring
@@ -21,6 +21,46 @@ describe YARD::Parser::SourceParser do
       Registry.at("Hello::Hi#me").docstring.should == "Docstring\nDocstring2"
       Registry.at("Hello::Hi#me").docstring.line_range.should == (3..4)
     end
+    
+    it "should only use prepended comments for an object" do
+      YARD.parse_string(<<-eof)
+        # Test
+        
+        # PASS
+        module Hello
+        end # FAIL
+      eof
+      Registry.at(:Hello).docstring.should == "PASS"
+    end
+    
+    it "should add comments appended to an object's first line" do
+      YARD.parse_string <<-eof
+        module Hello # PASS
+          HELLO
+        end
+        module Hello2
+        end # FAIL
+
+
+        module Hello3 # PASS
+          # CANNOT DIFFERENTIATE
+          def x; end
+        end
+      eof
+
+      # TODO: unify behaviour
+      if RUBY18
+        Registry.at(:Hello).docstring.should == ""
+        Registry.at(:Hello2).docstring.should == "FAIL"
+        Registry.at(:Hello3).docstring.should == ""
+        Registry.at('Hello3#x').docstring.should == "CANNOT DIFFERENTIATE"
+      else
+        Registry.at(:Hello).docstring.should == "PASS"
+        Registry.at(:Hello2).docstring.should == ""
+        Registry.at(:Hello3).docstring.should == ""
+        Registry.at('Hello3#x').docstring.should == "PASS\nCANNOT DIFFERENTIATE"
+      end
+    end
   end
 
   describe '#parse' do
@@ -65,7 +105,13 @@ describe YARD::Parser::SourceParser do
       msgs[2].should =~ /Missing object MyModule/
       msgs[3].should =~ /Processing .+parse_in_order_002.+/
       msgs[4].should =~ /Re-processing .+parse_in_order_001.+/
-      msgs[5].should =~ /Object MyModule successfully resolved/
+    end
+    
+    it "should attempt to order files by length (process toplevel files first)" do
+      %w(a a/b a/b/c).each do |file|
+        IO.should_receive(:read).with(file).ordered.and_return('')
+      end
+      YARD.parse %w(a/b/c a/b a)
     end
   end