deg-yard 0.8.7.1

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

@@ -0,0 +1,126 @@
+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
+  def /(other) 'hi' end
+
+  attr_reader :method1
+
+  def method1
+    def dynamic; end
+  end
+
+  def self.method2; end
+
+  # Docstring
+  def String :: hello; "" end
+
+  def self.new() end
+
+  def [](key = 'default') puts key end
+  def []=(key, value) end
+  def
+allowed?
+end
+
+  def ` param; end
+  def /(x = File.new('x', 'w'), y = 2) end
+  def |; end; def =~ ()
+  def -@; end;
+end
+  def *(o) def +@; end
+    def ~@
+    end end
+  def &(o) end
+  def %(o) end
+  def ^(o) 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
+
+  # No return tag
+  def boolean?; end
+
+  # @return without type
+  def boolean2?; end
+
+  # @return [NotBoolean, nil]
+  def boolean3?; end
+
+  # @overload rainy?
+  #   @return whether today is the rainy day.
+  def rainy?; end
+
+  attr_writer :attr_name
+  def attr_name; end
+
+  attr_reader :attr_name2
+  def attr_name2=; end
+
+  # @option opts :bar [String] It's bar!
+  def auto_opts(opts)
+  end
+end
+
+CONST = Foo
+def CONST.meth_on_const; end
+CONST2 = CONST
+def CONST2.meth2_on_const; end
+
+class D
+  alias b a
+
+  # foo bar
+  def a; end
+end
+
+class E
+  # @!macro prop
+  #   @!method $1(value)
+  #   $3
+  #   @return [$2]
+  def self.property(name, ret_type, docstring)
+  end
+
+  property :foo, String, "create a foo"
+
+  # @!macro xyz
+  #   @!method $1
+  def xyz; end
+
+  xyz :a
+end
+
+module F
+  class A
+    def foo; end
+
+    def end
+    end
+
+    # PASS
+    def bar; end
+  end
+end

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

@@ -0,0 +1,37 @@
+module A; end
+module B;
+  module C; end
+  module D; end
+end
+
+QQQ = B::D
+
+class X
+  include A
+  include B, B::C, NOTEXIST
+end
+
+module Y
+  include B::C, B if X == 2
+  include A
+  include QQQ
+
+  class << self; include A; end
+end
+
+module Z
+  include A, B
+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/examples/module_handler_001.rb.txt

@@ -0,0 +1,29 @@
+module ModName
+  private
+
+  # Docstring
+  module OtherModName
+  end
+end
+
+module            StressTest; end
+
+module A; end
+
+module Q
+	module A::B
+	end
+	module FOO; end
+end
+
+module ::Kernel
+  def x; end
+end
+
+module A; end
+module B; end
+module C; end
+class D; include A; include B; include C; end
+
+Z = Q
+module Z::FOO::A; end

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

@@ -0,0 +1,8 @@
+module A
+  Foo = 1
+  class B; end
+  module C; end
+  module D; end
+
+  private_constant :Foo, 'B', C
+end

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

@@ -0,0 +1,11 @@
+class A < NotHandler
+  process { hello }
+end
+
+class B < YARD::Handlers::Ruby::Base
+  process { test }
+end
+
+class C < YARD::Handlers::Ruby::Legacy::Base
+  process do test end
+end

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

@@ -0,0 +1,32 @@
+class Testing
+  def pub; end
+
+  private
+
+  def priv; end
+  def notpriv; end
+  def notpriv2; end
+  def notpriv?; end
+
+  protected
+
+  def prot; end
+
+  public
+
+  def pub2; end
+
+  protected :notpriv, 'notpriv2', :notpriv?
+
+  private name
+  private *argument
+  private *(method_call)
+
+  def Foo; end
+  private :Foo
+
+  private
+
+  class Bar; end
+  module Baz; end
+end

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

@@ -0,0 +1,54 @@
+class Testing
+  # Ignore yields outside methods
+  yield x, y, z
+
+  # Should document this
+  def mymethod
+    yield
+  end
+
+  # Has yield and yieldparam documentation
+  # @yield [a, b] Blah
+  # @yieldparam a Blah
+  # @yieldparam b Blah
+  def mymethod2
+    yield(b, a) # Yield something else
+  end
+
+  # Has yield documentation only
+  # @yield [a, b]
+  def mymethod3
+    yield self # Should not be changed
+  end
+
+  # Has yieldparam documentation only
+  # @yieldparam _self BLAH
+  def mymethod4
+    yield self
+  end
+
+  # Some weird possibilities..
+  # Document it all.
+
+
+  def mymethod5
+    yield :a, b, self, File.read('file', 'w'), CONSTANT if x == 2
+  end
+
+  def mymethod6
+    yield(b, a)
+  end
+
+  def mymethod7
+    yield a
+    yield b
+  end
+
+  def mymethod8
+    yield self
+  end
+
+  def mymethod9
+    yield super
+  end
+end

data/spec/handlers/exception_handler_spec.rb

@@ -0,0 +1,48 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}ExceptionHandler" do
+  before(:all) { parse_file :exception_handler_001, __FILE__ }
+
+  it "should not document an exception outside of a method" do
+    P('Testing').has_tag?(:raise).should == false
+  end
+
+  it "should document a valid raise" do
+    P('Testing#mymethod').tag(:raise).types.should == ['ArgumentError']
+  end
+
+  it "should only document non-dynamic raises" do
+    P('Testing#mymethod2').tag(:raise).should be_nil
+    P('Testing#mymethod6').tag(:raise).should be_nil
+    P('Testing#mymethod7').tag(:raise).should be_nil
+  end
+
+  it "should treat ConstantName.new as a valid exception class" do
+    P('Testing#mymethod8').tag(:raise).types.should == ['ExceptionClass']
+  end
+
+  it "should not document a method with an existing @raise tag" do
+    P('Testing#mymethod3').tag(:raise).types.should == ['A']
+  end
+
+  it "should only document the first raise message of a method (limitation of exception handler)" do
+    P('Testing#mymethod4').tag(:raise).types.should == ['A']
+  end
+
+  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
+
+  it "should handle raise expressions that are method calls" do
+    P('Testing#mymethod10').tag(:raise).should be_nil
+    P('Testing#mymethod11').tag(:raise).should be_nil
+  end
+
+  it "should ignore empty raise call" do
+    P('Testing#mymethod12').tag(:raise).should be_nil
+  end
+end

data/spec/handlers/extend_handler_spec.rb

@@ -0,0 +1,23 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}ExtendHandler" do
+  before(:all) { 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
+
+  it "should extend module with correct namespace" do
+    Registry.at('Q::R::S').class_mixins.first.path.should == 'A'
+  end
+
+  it "should not allow extending self if object is a class" do
+    undoc_error "class Foo; extend self; end"
+  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

data/spec/handlers/method_condition_handler_spec.rb

@@ -0,0 +1,14 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}MethodConditionHandler" do
+  before(:all) { 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

@@ -0,0 +1,184 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}MethodHandler" do
+  before(:all) do
+    log.enter_level(Logger::ERROR) do
+      parse_file :method_handler_001, __FILE__
+    end
+  end
+
+  it "should add methods to parent's #meths list" do
+    P(:Foo).meths.should include(P("Foo#method1"))
+  end
+
+  it "should parse/add class methods (self.method2)" do
+    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 be_instance_of(CodeObjects::MethodObject)
+  end
+
+  [:[], :[]=, :allowed?, :/, :=~, :==, :`, :|, :*, :&, :%, :'^', :-@, :+@, :'~@'].each do |name|
+    it "should allow valid method #{name}" do
+      Registry.at("Foo##{name}").should_not be_nil
+    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
+
+  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
+
+  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 == :bar
+    o1.parameters.should == [['a', nil], ['b', "1"]]
+    o1.tag(:return).type.should == "String"
+
+    o2 = meth.tags(:overload)[1]
+    o2.name.should == :baz
+    o2.parameters.should == [['b', nil], ['c', nil]]
+    o2.tag(:return).type.should == "Fixnum"
+
+    o3 = meth.tags(:overload)[2]
+    o3.name.should == :bang
+    o3.parameters.should == [['d', nil], ['e', nil]]
+    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
+
+  it "should add @return [Boolean] tag to methods ending in ? without return types" do
+    meth = P('Foo#boolean?')
+    meth.should have_tag(:return)
+    meth.tag(:return).types.should == ['Boolean']
+  end
+
+  it "should add Boolean type to return tag without types" do
+    meth = P('Foo#boolean2?')
+    meth.should have_tag(:return)
+    meth.tag(:return).types.should == ['Boolean']
+  end
+
+  it "should not change return type for method ending in ? with return types set" do
+    meth = P('Foo#boolean3?')
+    meth.should have_tag(:return)
+    meth.tag(:return).types.should == ['NotBoolean', 'nil']
+  end
+
+  it "should not change return type for method ending in ? with return types set by @overload" do
+    meth = P('Foo#rainy?')
+    meth.should have_tag(:overload)
+    meth.tag(:overload).should have_tag(:return)
+    meth.should_not have_tag(:return)
+  end
+
+  it "should add method writer to existing attribute" do
+    Registry.at('Foo#attr_name').should be_reader
+    Registry.at('Foo#attr_name=').should be_writer
+  end
+
+  it "should add method reader to existing attribute" do
+    Registry.at('Foo#attr_name2').should be_reader
+    Registry.at('Foo#attr_name2=').should be_writer
+  end
+
+  it "should generate an options parameter if @option refers to an undocumented parameter" do
+    meth = P('Foo#auto_opts')
+    meth.should have_tag(:param)
+    meth.tag(:param).name.should == "opts"
+    meth.tag(:param).types.should == ["Hash"]
+  end
+
+  it "should raise an undocumentable error when a method is defined on an object instance" do
+    undoc_error "error = Foo; def error.at(foo) end"
+    Registry.at('error').should be_nil
+  end
+
+  it "should allow class method to be defined on constant reference object" do
+    Registry.at('Foo.meth_on_const').should_not be_nil
+    Registry.at('Foo.meth2_on_const').should_not be_nil
+  end
+
+  it "should copy alias information on method (re-)definition to new method" do
+    Registry.at('D').aliases.should be_empty
+    Registry.at('D#b').is_alias?.should == false
+    Registry.at('D#a').is_alias?.should == false
+  end
+
+  it "should add macros for class methods" do
+    macro = CodeObjects::MacroObject.find('prop')
+    macro.should_not be_nil
+    macro.macro_data.should == "@!method $1(value)\n$3\n@return [$2]"
+    macro.method_object.should == Registry.at('E.property')
+    macro.should be_attached
+    obj = Registry.at('E#foo')
+    obj.should_not be_nil
+    obj.docstring.should == 'create a foo'
+    obj.signature.should == 'def foo(value)'
+    obj.tag(:return).types.should == ['String']
+  end
+
+  it "should handle macros on any object" do
+    macro = CodeObjects::MacroObject.find('xyz')
+    macro.should_not be_nil
+    macro.macro_data.should == '@!method $1'
+  end
+
+  it "should skip macros on instance methods" do
+    Registry.at('E#a').should be_nil
+  end
+
+  it "should warn if the macro name is invalid" do
+    log.should_receive(:warn).with(/Invalid directive.*@!macro/)
+    YARD.parse_string "class Foo\n# @!macro\ndef self.foo; end\nend"
+  end
+
+  it "should handle 'def end' methods" do
+    obj = Registry.at('F::A#foo')
+    obj.should_not be_nil
+    obj = Registry.at('F::A#bar')
+    obj.should_not be_nil
+    obj.docstring.should == 'PASS'
+  end
+end