yard 0.2.1 → 0.2.2

data/spec/handlers/base_spec.rb

@@ -0,0 +1,165 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+include Parser
+
+describe YARD::Handlers::Base, "#handles and inheritance" do
+  before do
+    Handlers::Base.stub!(:inherited)
+  end
+  
+  it "should keep track of subclasses" do
+    Handlers::Base.should_receive(:inherited).once
+    class TestHandler < Handlers::Base; end
+  end
+  
+  it "should handle a string input" do
+    class TestStringHandler < Handlers::Base
+      handles "hello"
+    end
+
+    TestStringHandler.handles?(TokenList.new("hello world")).should == true
+    TestStringHandler.handles?(TokenList.new("nothello world")).should == false
+  end
+  
+  it "should handle regex input" do
+    class TestRegexHandler < Handlers::Base
+      handles /^nothello$/
+    end
+
+    TestRegexHandler.handles?(TokenList.new("nothello")).should == true
+    TestRegexHandler.handles?(TokenList.new("not hello hello")).should == false
+  end
+
+  it "should handle token input" do
+    class TestTokenHandler < Handlers::Base
+      handles TkMODULE
+    end
+
+    TestTokenHandler.handles?(TokenList.new("module")).should == true
+    TestTokenHandler.handles?(TokenList.new("if")).should == false
+  end
+  
+  it "should raise NotImplementedError if process is called on a class with no #process" do
+    class TestNotImplementedHandler < Handlers::Base
+      handles TkMODULE
+    end
+    
+    lambda { TestNotImplementedHandler.new(0, 0).process }.should raise_error(NotImplementedError)
+  end
+end
+
+describe YARD::Handlers::Base, "#tokval" do 
+  include RubyToken
+  
+  before { @handler = Handlers::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::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
+end

data/spec/handlers/class_handler_spec.rb

@@ -0,0 +1,68 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::Handlers::ClassHandler do
+  before { parse_file :class_handler_001, __FILE__ }
+  
+  it "should parse a class block with docstring" do
+    P("A").docstring.should == "Docstring"
+  end
+  
+  it "should handle complex class names" do
+    P("A::B::C").should_not == nil
+  end
+  
+  it "should handle the subclassing syntax" do
+    P("A::B::C").superclass.should == P(:String)
+    P("A::X").superclass.should == Registry.at("A::B::C")
+  end
+  
+  it "should interpret class << self as a class level block" do
+    P("A::classmethod1").should_not == nil
+  end
+  
+  it "should interpret class << ClassName as a class level block in ClassName's namespace" do
+    P("A::B::C::Hello").should be_instance_of(CodeObjects::MethodObject)
+  end
+  
+  it "should make visibility public when parsing a block" do
+    P("A::B::C#method1").visibility.should == :public
+  end
+  
+  it "should set superclass type to :class if it is a Proxy" do
+    P("A::B::C").superclass.type.should == :class
+  end
+  
+  it "should look for a superclass before creating the class if it shares the same name" do
+    P('B::A').superclass.should == P('A')
+  end
+
+  it "should raise an UndocumentableError if the class is invalid" do
+    ["CallMethod('test')", "VSD^#}}", 'not.aclass', 'self'].each do |klass|
+      undoc_error "class #{klass}; end"
+    end
+  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)
+    P('Test6').superclass.should == P(:NotDelegateClass)
+  end
+  
+  it "should handle superclass with OStruct.new or Struct.new syntax (superclass should be OStruct/Struct)" do
+    P('Test3').superclass.should == P(:Struct)
+    P('Test4').superclass.should == P(:OStruct)
+  end
+  
+  it "should handle DelegateClass(CLASSNAME) superclass syntax" do
+    P('Test5').superclass.should == P(:Array)
+  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|
+      Registry.clear
+      undoc_error "class A < #{klass}; end"
+      Registry.at('A').should_not be_nil
+      Registry.at('A').superclass.should == P(:Object)
+    end
+  end
+end

data/spec/handlers/class_variable_handler_spec.rb

@@ -0,0 +1,9 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::Handlers::ClassVariableHandler do
+  before { 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\""
+  end
+end

data/spec/handlers/constant_handler_spec.rb

@@ -0,0 +1,13 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::Handlers::ConstantHandler do
+  before { parse_file :constant_handler_001, __FILE__ }
+  
+  it "should not parse constants inside methods" do
+    Registry.at("A::B::SOMECONSTANT").source.should == "SOMECONSTANT= \"hello\""
+  end
+  
+  it "should only parse valid constants" do
+    Registry.at("A::B::notaconstant").should be_nil
+  end
+end

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

@@ -0,0 +1,24 @@
+module A
+  def a; end
+  alias_method :b, :a
+  
+  # Handle keyword syntax too
+  alias :c :a
+  alias d? a
+  alias [] a
+  alias []= a
+  alias @- a
+  alias % a
+  alias * a
+end
+
+class C
+  def x; end
+end
+
+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

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

@@ -0,0 +1,19 @@
+module A
+  attr_writer :x
+end
+
+class B
+  class << self
+    attr_accessor :z
+  end
+
+  attr :a, true
+  attr :a2, false
+  attr :a3
+  # Docstring
+  attr_reader :b, :c, :d
+  attr_writer :e
+  attr_accessor 'f'
+
+  attr_accessor :z
+end

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

@@ -0,0 +1,39 @@
+# Docstring
+class A
+  module B; end
+  private
+  class B::C < String; 
+    def method1; end
+    def method2; end
+  end
+  class X<B::C
+  end
+  class<<self
+    def classmethod1; end
+  end
+
+  class << A::B::C; def Hello; end end
+end
+
+module B
+  class A < A
+  end
+end
+
+class Test1 < R "something"
+end
+
+class Test2 < R(/something/)
+end
+
+class Test3 < Struct.new(:foo, :bar)
+end
+
+class Test4 < OStruct.new
+end
+
+class Test5 < DelegateClass(Array)
+end
+
+class Test6 < NotDelegateClass(Array)
+end

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

@@ -0,0 +1,9 @@
+module A
+  class B
+    @@somevar = "hello"
+
+    def method
+      @@somevar = "don't document this"
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+module A
+  class B
+	notaconstant = 2
+    SOMECONSTANT= "hello"
+
+    def method
+      SOMECONSTANT = "don't document this"
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+class Testing
+  # Ignore yields outside methods
+  raise NoMethodError, "reason"
+  
+  # Should document this
+  def mymethod
+    raise ArgumentError, "Argument is missing"
+  end
+  
+  # Don't document this
+  def mymethod2
+    raise(a) 
+  end
+  
+  # Don't document this (docstring takes precedence)
+  # @raise [A]
+  def mymethod3 
+    raise SomethingElse
+  end
+  
+  # Only document the first one (limitation of exc handler)
+  def mymethod4 
+    raise(A)
+    raise B, "Argument", somethingelse
+  end
+  
+  def mymethod5
+    raise YARD::Handlers::UndocumentableError
+  end
+  
+  def mymethod6
+    raise YARD::Handlers.constants("test")
+  end
+  
+  def mymethod7
+    raise MethodCall('argument')
+  end
+  
+  def mymethod8
+    raise ExceptionClass.new('blah')
+  end
+end

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

@@ -0,0 +1,35 @@
+class Foo
+  def ==(other)
+ 	'hello' 
+  end
+  def /(other) 'hi' end
+
+  attr_reader :method1
+
+  def method1
+    def dynamic; end
+  end
+ 
+  def self.method2; end
+
+  # Docstring
+  def String :: hello; "" end
+
+  def [](key) puts key end
+  def []=(key, value) end
+  def 
+allowed?
+end
+
+  def ` param; end
+  def /(x) end
+  def |; end; def =~ ()
+  def -@; end; 
+end
+  def *(o) def +@; end
+    def ~@
+    end end
+  def &(o) end
+  def %(o) end
+  def ^(o) end
+end