yard 0.2.2 → 0.2.3

data/spec/handlers/class_handler_spec.rb

@@ -1,6 +1,6 @@
 require File.dirname(__FILE__) + '/spec_helper'
 
-describe YARD::Handlers::ClassHandler do
+describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}ClassHandler" do
   before { parse_file :class_handler_001, __FILE__ }
   
   it "should parse a class block with docstring" do
@@ -17,7 +17,7 @@ describe YARD::Handlers::ClassHandler do
   end
   
   it "should interpret class << self as a class level block" do
-    P("A::classmethod1").should_not == nil
+    P("A.classmethod1").should_not == nil
   end
   
   it "should interpret class << ClassName as a class level block in ClassName's namespace" do
@@ -42,6 +42,10 @@ describe YARD::Handlers::ClassHandler do
     end
   end
   
+  it "should handle class definitions in the form ::ClassName" do
+    Registry.at("MyRootClass").should_not be_nil
+  end
+  
   it "should handle superclass as a constant-style method (camping style < R /path/)" do
     P('Test1').superclass.should == P(:R)
     P('Test2').superclass.should == P(:R)
@@ -57,12 +61,49 @@ describe YARD::Handlers::ClassHandler do
     P('Test5').superclass.should == P(:Array)
   end
   
+  it "should handle a superclass of the same name in the form ::ClassName" do
+    P('Q::Logger').superclass.should == P(:Logger)
+  end
+  
   it "should raise an UndocumentableError if the superclass is invalid but it should create the class." do
-    ["VSD^#}}", 'not.aclass', 'self', 'AnotherClass.new'].each do |klass|
+    ['@@INVALID', 'hi', '$MYCLASS', 'AnotherClass.new'].each do |klass|
       Registry.clear
       undoc_error "class A < #{klass}; end"
       Registry.at('A').should_not be_nil
       Registry.at('A').superclass.should == P(:Object)
     end
   end
+  
+  it "should document 'class << SomeConstant' by using SomeConstant's value as a reference to the real class name" do
+    Registry.at('String.classmethod').should_not be_nil
+  end
+  
+  it "should allow class << SomeRubyClass to create the class if it does not exist" do
+    Registry.at('Symbol.toString').should_not be_nil
+  end
+  
+  it "should raise an UndocumentableError if the constant class reference 'class << SomeConstant' does not point to a valid class name" do
+    ['not.aclass', 'self', 'AnotherClass.new'].each do |klass|
+      Registry.clear
+      undoc_error <<-eof
+        CONST = #{klass}
+        class << CONST; end
+      eof
+      Registry.at(klass).should be_nil
+    end
+  end
+  
+  it "should document 'class Exception' without running into superclass issues" do
+    Parser::SourceParser.parse_string <<-eof
+      class Exception
+      end
+    eof
+    Registry.at(:Exception).should_not be_nil
+  end
+  
+  it "should document 'class RT < XX::RT' with proper superclass even if XX::RT is a proxy" do
+    Registry.at(:RT).should_not be_nil
+    Registry.at(:RT).superclass.should == P('XX::RT')
+  end
+  
 end

data/spec/handlers/class_variable_handler_spec.rb

@@ -1,6 +1,6 @@
 require File.dirname(__FILE__) + '/spec_helper'
 
-describe YARD::Handlers::ClassVariableHandler do
+describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}ClassVariableHandler" do
   before { parse_file :class_variable_handler_001, __FILE__ }
   
   it "should not parse class variables inside methods" do

data/spec/handlers/constant_handler_spec.rb

@@ -1,6 +1,6 @@
 require File.dirname(__FILE__) + '/spec_helper'
 
-describe YARD::Handlers::ConstantHandler do
+describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}ConstantHandler" do
   before { parse_file :constant_handler_001, __FILE__ }
   
   it "should not parse constants inside methods" do

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

@@ -7,9 +7,11 @@ module A
   alias d? a
   alias [] a
   alias []= a
-  alias @- a
+  alias -@ a
   alias % a
   alias * a
+  alias for a
+  alias ConstantName a
 end
 
 class C
@@ -20,5 +22,7 @@ class B < C
   alias_method(:q, :x)
   alias_method :r?, :x
   alias_method :s, :to_s 
-  alias_method :t, :inspect if 500 = 3 * CONSTANT
-end
+  alias_method :t, :inspect if 500 == 3 * CONSTANT
+  alias_method :<<, :a
+  alias_method :for, :a
+end

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

@@ -0,0 +1,61 @@
+class A
+  if some_condition
+    def a; end
+  elsif 1 == 1
+    def b; end
+  else
+    def c; end
+  end
+  
+  def d; end if 50 * 2 == 101
+  
+  unless false
+    def e; end
+  else
+    def enot; end
+  end
+  
+  def g; end unless 5 * 2 == 101
+
+  def h
+    if 1
+      def hnot; end
+    end
+  end
+  
+  if defined? A
+    def j; end
+  else
+    def jnot; end
+  end
+  
+  if defined? RUBY_VERSION
+    def k; end
+  else
+    def knot; end
+  end
+  
+  if 0
+    def nnot; end
+  else
+    def n; end
+  end
+  
+  if 256
+    def o; end
+  else
+    def onot; end
+  end
+  
+  if true
+    def p; end
+  else
+    def pnot; end
+  end
+  
+  if false
+    def qnot; end
+  else
+    def q; end
+  end
+end

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

@@ -20,6 +20,8 @@ module B
   end
 end
 
+class RT < XX::RT; end
+
 class Test1 < R "something"
 end
 
@@ -36,4 +38,35 @@ class Test5 < DelegateClass(Array)
 end
 
 class Test6 < NotDelegateClass(Array)
+end
+
+class ::MyRootClass
+end
+
+module Holder
+  module SomeMod
+    class Importer
+      def parse; end
+    end
+  end
+end
+
+module Holder
+  class Importer < Holder::SomeMod::Importer
+    def a; end
+  end
+end
+
+class String; end
+CONST = String
+class << CONST
+  def classmethod; end
+end
+
+module Q
+  class Logger < ::Logger; end
+end
+
+class << Symbol
+  alias toString to_s
 end

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

@@ -25,7 +25,7 @@ class Testing
   end
   
   def mymethod5
-    raise YARD::Handlers::UndocumentableError
+    raise YARD::Parser::UndocumentableError
   end
   
   def mymethod6

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

@@ -0,0 +1,8 @@
+module A; end
+module B
+  extend A
+end
+
+module C
+  extend self
+end

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

@@ -0,0 +1,10 @@
+def a
+  if 1
+    # ignore this
+    def b; end
+  end
+  
+  # don't ignore these even though we know they're not executed
+  def c; end if false
+  def d; end unless true
+end 

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

@@ -1,6 +1,6 @@
 class Foo
   def ==(other)
- 	'hello' 
+    'hello' 
   end
   def /(other) 'hi' end
 
@@ -15,14 +15,14 @@ class Foo
   # Docstring
   def String :: hello; "" end
 
-  def [](key) puts key end
+  def [](key = 'default') puts key end
   def []=(key, value) end
   def 
 allowed?
 end
 
   def ` param; end
-  def /(x) end
+  def /(x = File.new('x', 'w'), y = 2) end
   def |; end; def =~ ()
   def -@; end; 
 end
@@ -32,4 +32,16 @@ end
   def &(o) end
   def %(o) end
   def ^(o) end
-end
+  
+  def optsmeth(x, opts = {}) end
+  def blockmeth(x, &block) end
+
+  # @param a [Fixnum]
+  # @overload def bar(a, b = 1)
+  #   @param a [String]
+  #   @return [String]
+  # @overload def baz(b, c)
+  #   @return [Fixnum]
+  # @overload bang(d, e)
+  def foo(*args); end
+end

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

@@ -1,5 +1,10 @@
 module A; end
-module B; module C; end end
+module B; 
+  module C; end 
+  module D; end
+end
+
+QQQ = B::D
 
 class X
   include A
@@ -9,4 +14,7 @@ end
 module Y
   include B::C, B if X == 2
   include A
-end
+  include QQQ
+
+  class << self; include A; end
+end

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

@@ -13,4 +13,8 @@ module A; end
 module Q
 	module A::B
 	end
+end
+
+module ::Kernel
+  def x; end
 end

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

@@ -16,5 +16,5 @@ class Testing
 
   def pub2; end
 
-  public :notpriv, 'notpriv2', :notpriv?
+  protected :notpriv, 'notpriv2', :notpriv?
 end

data/spec/handlers/exception_handler_spec.rb

@@ -1,6 +1,6 @@
 require File.dirname(__FILE__) + '/spec_helper'
 
-describe YARD::Handlers::ExceptionHandler do
+describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}ExceptionHandler" do
   before { parse_file :exception_handler_001, __FILE__ }
   
   it "should not document an exception outside of a method" do
@@ -30,6 +30,6 @@ describe YARD::Handlers::ExceptionHandler do
   end
   
   it "should handle complex class names" do
-    P('Testing#mymethod5').tag(:raise).types.should == ['YARD::Handlers::UndocumentableError']
+    P('Testing#mymethod5').tag(:raise).types.should == ['YARD::Parser::UndocumentableError']
   end
 end

data/spec/handlers/extend_handler_spec.rb

@@ -0,0 +1,15 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe "YARD::Handlers::Ruby::#{RUBY18 ? "Legacy::" : ""}ExtendHandler" do
+  before { parse_file :extend_handler_001, __FILE__ }
+
+  it "should include modules at class scope" do
+    Registry.at(:B).class_mixins.should == [P(:A)]
+    Registry.at(:B).instance_mixins.should be_empty
+  end
+
+  it "should handle a module extending itself" do
+    Registry.at(:C).class_mixins.should == [P(:C)]
+    Registry.at(:C).instance_mixins.should be_empty
+  end
+end

data/spec/handlers/legacy_base_spec.rb

@@ -0,0 +1,128 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+include Parser::Ruby::Legacy
+
+describe YARD::Handlers::Ruby::Legacy::Base, "#tokval" do 
+  
+  before { @handler = Handlers::Ruby::Legacy::Base.new(nil, nil) } 
+  
+  def tokval(code, *types)
+    @handler.send(:tokval, TokenList.new(code).first, *types)
+  end
+  
+  it "should return the String's value without quotes" do
+    tokval('"hello"').should == "hello"
+  end
+  
+  it "should not allow interpolated strings with TkSTRING" do
+    tokval('"#{c}"', RubyToken::TkSTRING).should be_nil
+  end
+  
+  it "should return a Symbol's value as a String (as if it was done via :name.to_sym)" do
+    tokval(':sym').should == :sym
+  end
+  
+  it "should return nil for any non accepted type" do
+    tokval('identifier').should be_nil
+    tokval(':sym', RubyToken::TkId).should be_nil
+  end
+  
+  it "should accept TkVal tokens by default" do
+    tokval('2.5').should == 2.5
+    tokval(':sym').should == :sym
+  end
+  
+  it "should accept any ID type if TkId is set" do
+    tokval('variable', RubyToken::TkId).should == "variable"
+    tokval('CONSTANT', RubyToken::TkId).should == "CONSTANT"
+  end
+  
+  it "should allow extra token types to be accepted" do 
+    tokval('2.5', RubyToken::TkFLOAT).should == 2.5
+    tokval('2', RubyToken::TkFLOAT).should be_nil
+    tokval(':symbol', RubyToken::TkFLOAT).should be_nil
+  end
+  
+  it "should allow :string for any string type" do
+    tokval('"hello"', :string).should == "hello"
+    tokval('"#{c}"', :string).should == '#{c}'
+  end
+  
+  it "should not include interpolated strings when using :attr" do
+    tokval('"#{c}"', :attr).should be_nil
+  end
+  
+  it "should allow any number type with :number" do
+    tokval('2.5', :number).should == 2.5
+    tokval('2', :number).should == 2
+  end
+  
+  it "should should allow method names with :identifier" do
+    tokval('methodname?', :identifier).should == "methodname?"
+  end
+  
+  #it "should obey documentation expectations" do docspec end
+end
+
+describe YARD::Handlers::Base, "#tokval_list" do 
+  before { @handler = Handlers::Ruby::Legacy::Base.new(nil, nil) } 
+  
+  def tokval_list(code, *types)
+    @handler.send(:tokval_list, TokenList.new(code), *types)
+  end
+  
+  it "should return the list of tokvalues" do
+    tokval_list(":a, :b, \"\#{c}\", 'd'", :attr).should == [:a, :b, 'd']
+    tokval_list(":a, :b, File.read(\"\#{c}\", ['w']), :d", 
+      RubyToken::Token).should  == [:a, :b, 'File.read("#{c}", [\'w\'])', :d]
+  end
+  
+  it "should try to skip any invalid tokens" do
+    tokval_list(":a, :b, \"\#{c}\", :d", :attr).should  == [:a, :b, :d]
+    tokval_list(":a, :b, File.read(\"\#{c}\", 'w', File.open { }), :d", :attr).should  == [:a, :b, :d]
+    tokval_list("CONST1, identifier, File.read(\"\#{c}\", 'w', File.open { }), CONST2", 
+      RubyToken::TkId).should  == ['CONST1', 'identifier', 'CONST2']
+  end
+  
+  it "should ignore a token if another invalid token is read before a comma" do
+    tokval_list(":a, :b XYZ, :c", RubyToken::TkSYMBOL).should == [:a, :c]
+  end
+  
+  it "should stop on most keywords" do
+    tokval_list(':a rescue :x == 5', RubyToken::Token).should == [:a]
+  end
+  
+  it "should handle ignore parentheses that begin the token list" do
+    tokval_list('(:a, :b, :c)', :attr).should == [:a, :b, :c]
+  end
+  
+  it "should end when a closing parenthesis was found" do
+    tokval_list(':a, :b, :c), :d', :attr).should == [:a, :b, :c]
+  end
+  
+  it "should ignore parentheses around items in a list" do
+    tokval_list(':a, (:b), :c, (:d TEST), :e, [:f], :g', :attr).should == [:a, :b, :c, :e, :g]
+    tokval_list(':a, (((:f)))', :attr).should == [:a, :f]
+    tokval_list(':a, ([:f]), :c)', RubyToken::Token).should == [:a, '[:f]', :c]
+  end
+  
+  it "should not stop on a true/false/self keyword (cannot handle nil)" do
+    tokval_list(':a, true, :b, self, false, :c, nil, File, super, if, XYZ', 
+      RubyToken::Token).should == [:a, true, :b, 'self', false, :c, 'File', 'super']
+  end
+  
+  it "should ignore invalid commas" do
+    tokval_list(":a, :b, , :d").should == [:a, :b, :d]
+  end
+  
+  it "should return an empty list if no matches were found" do
+    tokval_list('attr_accessor :x').should == []
+  end
+  
+  it "should treat {} as a valid value" do
+    # FIXME: tokval_list destroys extra spaces surrounding the '=' in
+    #        this situation. This is technically a design flaw of the
+    #        tokval parser, but this is now the expected behaviour.
+    tokval_list("opts = {}", :all).should == ["opts={}"]
+  end
+end