deg-yard 0.8.7.1

data/spec/handlers/c/mixin_handler_spec.rb

@@ -0,0 +1,27 @@
+require File.dirname(__FILE__) + "/spec_helper"
+
+describe YARD::Handlers::C::MixinHandler do
+  it "should add includes to modules or classes" do
+    parse_init <<-eof
+      mFoo = rb_define_module("Foo");
+      cBar = rb_define_class("Bar", rb_cObject);
+      mBaz = rb_define_module("Baz");
+      rb_include_module(cBar, mFoo);
+      rb_include_module(mBaz, mFoo);
+    eof
+    foo = Registry.at('Foo')
+    bar = Registry.at('Bar')
+    baz = Registry.at('Baz')
+    bar.mixins(:instance).should == [foo]
+    baz.mixins(:instance).should == [foo]
+  end
+
+  it "should add include as proxy if symbol lookup fails" do
+    parse_init <<-eof
+      mFoo = rb_define_module("Foo");
+      rb_include_module(mFoo, mXYZ);
+    eof
+    foo = Registry.at('Foo')
+    foo.mixins(:instance).should == [P('XYZ')]
+  end
+end

data/spec/handlers/c/module_handler_spec.rb

@@ -0,0 +1,38 @@
+require File.dirname(__FILE__) + "/spec_helper"
+
+describe YARD::Handlers::C::ClassHandler do
+  it "should register modules" do
+    parse_init 'mFoo = rb_define_module("Foo");'
+    Registry.at('Foo').type.should == :module
+  end
+
+  it "should register classes under namespaces" do
+    parse_init 'mFoo = rb_define_module_under(mBar, "Foo");'
+    Registry.at('Bar::Foo').type.should == :module
+  end
+
+  it "should remember symbol defined with class" do
+    parse_init(<<-eof)
+      cXYZ = rb_define_module("Foo");
+      rb_define_method(cXYZ, "bar", bar, 0);
+    eof
+    Registry.at('Foo').type.should == :module
+    Registry.at('Foo#bar').should_not be_nil
+  end
+
+  it "should not associate declaration comments as module docstring" do
+    parse_init(<<-eof)
+      /* Docstring! */
+      mFoo = rb_define_module("Foo");
+    eof
+    Registry.at('Foo').docstring.should be_blank
+  end
+
+  it "should associate a file with the declaration" do
+    parse_init(<<-eof)
+      mFoo = rb_define_module("Foo");
+    eof
+    Registry.at('Foo').file.should == '(stdin)'
+    Registry.at('Foo').line.should == 2
+  end
+end

data/spec/handlers/c/override_comment_handler_spec.rb

@@ -0,0 +1,46 @@
+require File.dirname(__FILE__) + "/spec_helper"
+
+describe YARD::Handlers::C::OverrideCommentHandler do
+  [:class, :module].each do |type|
+    it "should handle Document-#{type}" do
+      parse(<<-eof)
+        void something;
+        /* Document-#{type}: A
+         * Foo bar baz
+         */
+        void
+      eof
+      Registry.at('A').type.should == type
+      Registry.at('A').docstring.should == 'Foo bar baz'
+      Registry.at('A').file.should == '(stdin)'
+      Registry.at('A').line.should == 2
+    end
+  end
+
+  it "should handle multiple class/module combinations" do
+    parse(<<-eof)
+      /* Document-class: A
+       * Document-class: B
+       * Document-module: C
+       * Foo bar baz
+       */
+    eof
+    Registry.at('A').docstring.should == 'Foo bar baz'
+    Registry.at('B').docstring.should == 'Foo bar baz'
+    Registry.at('C').docstring.should == 'Foo bar baz'
+    Registry.at('C').type == :module
+  end
+
+  it "should handle Document-class with inheritance" do
+    parse(<<-eof)
+      /* Document-class: A < B
+       * Foo bar baz
+       */
+      void
+    eof
+    obj = Registry.at('A')
+    obj.type.should == :class
+    obj.docstring.should == 'Foo bar baz'
+    obj.superclass.should == P('B')
+  end
+end

data/spec/handlers/c/path_handler_spec.rb

@@ -0,0 +1,35 @@
+require File.dirname(__FILE__) + "/spec_helper"
+
+describe YARD::Handlers::C::PathHandler do
+  it 'should track variable names defined under namespaces' do
+    parse_init <<-eof
+      mFoo = rb_define_module("Foo");
+      cBar = rb_define_class_under(mFoo, "Bar", rb_cObject);
+      rb_define_method(cBar, "foo", foo, 1);
+    eof
+    Registry.at('Foo::Bar').should_not be_nil
+    Registry.at('Foo::Bar#foo').should_not be_nil
+  end
+
+  it 'should track variable names defined under namespaces' do
+    parse_init <<-eof
+      mFoo = rb_define_module("Foo");
+      cBar = rb_define_class_under(mFoo, "Bar", rb_cObject);
+      mBaz = rb_define_module_under(cBar, "Baz");
+      rb_define_method(mBaz, "foo", foo, 1);
+    eof
+    Registry.at('Foo::Bar::Baz').should_not be_nil
+    Registry.at('Foo::Bar::Baz#foo').should_not be_nil
+  end
+
+  it "should handle rb_path2class() calls" do
+    parse_init <<-eof
+      somePath = rb_path2class("Foo::Bar::Baz")
+      mFoo = rb_define_module("Foo");
+      cBar = rb_define_class_under(mFoo, "Bar", rb_cObject);
+      mBaz = rb_define_module_under(cBar, "Baz");
+      rb_define_method(somePath, "foo", foo, 1);
+    eof
+    Registry.at('Foo::Bar::Baz#foo').should_not be_nil
+  end
+end

data/spec/handlers/c/spec_helper.rb

@@ -0,0 +1,13 @@
+require File.dirname(__FILE__) + "/../spec_helper"
+
+def parse(src, file = '(stdin)')
+  YARD::Registry.clear
+  parser = YARD::Parser::SourceParser.new(:c)
+  parser.file = file
+  parser.parse(StringIO.new(src))
+end
+
+def parse_init(src)
+  YARD::Registry.clear
+  YARD.parse_string("void Init_Foo() {\n#{src}\n}", :c)
+end

data/spec/handlers/c/struct_handler_spec.rb

@@ -0,0 +1,15 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::Handlers::C::StructHandler do
+  after { Registry.clear }
+
+  it "should handle Struct class definitions" do
+    parse_init <<-eof
+      rb_cRange = rb_struct_define_without_accessor(
+          "Range", rb_cFoo, range_alloc,
+          "begin", "end", "excl", NULL);
+    eof
+    Registry.at('Range').type.should == :class
+    Registry.at('Range').superclass.should == P(:Foo)
+  end
+end

data/spec/handlers/class_condition_handler_spec.rb

@@ -0,0 +1,67 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}ClassConditionHandler" do
+  before(:all) { parse_file :class_condition_handler_001, __FILE__ }
+
+  def verify_method(*names)
+    names.each {|name| Registry.at("A##{name}").should_not be_nil }
+    names.each {|name| Registry.at("A##{name}not").should be_nil }
+  end
+
+  def no_undoc_error(code)
+    lambda { StubbedSourceParser.parse_string(code) }.should_not raise_error
+  end
+
+  it "should parse all unless blocks for complex conditions" do
+    verify_method :g
+  end
+
+  it "should not parse conditionals inside methods" do
+    verify_method :h
+  end
+
+  it "should only parse then block if condition is literal value `true`" do
+    verify_method :p
+  end
+
+  it "should only parse then block if condition is literal integer != 0" do
+    verify_method :o
+  end
+
+  it "should invert block to parse for literal condition if it's an unless block" do
+    verify_method :e
+  end
+
+  it "should handle conditions such as 'defined? VALUE'" do
+    verify_method :j, :k
+  end
+
+  it "should parse all if/elsif blocks for complex conditions" do
+    verify_method :a, :b, :c, :d
+  end
+
+  it "should only parse else block if condition is literal value `false`" do
+    verify_method :q
+  end
+
+  it "should only parse else block if condition is literal integer == 0" do
+    verify_method :n
+  end
+
+  it "should maintain visibility and scope state inside condition" do
+    Registry.at('A#m').visibility.should == :private
+    Registry.at('A#mnot').visibility.should == :private
+  end
+
+  it "should not fail on complex conditions" do
+    log.should_not_receive(:warn)
+    log.should_not_receive(:error)
+    no_undoc_error "if defined?(A) && defined?(B); puts 'hi' end"
+    no_undoc_error(<<-eof)
+      (<<-TEST) unless defined?(ABCD_MODEL_TEST)
+        'String'
+      TEST
+    eof
+    no_undoc_error "if caller.none? { |l| l =~ %r{lib/rails/generators\\.rb:(\\d+):in `lookup!'$} }; end"
+  end
+end

data/spec/handlers/class_handler_spec.rb

@@ -0,0 +1,246 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}ClassHandler" do
+  before(:all) { 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 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)
+    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 handle a superclass of the same name in the form ::ClassName" do
+    P('Q::Logger').superclass.should == P(:Logger)
+    P('Q::Foo').superclass.should_not == P('Q::Logger')
+  end
+
+  ["CallMethod('test')", "VSD^#}}", 'not.aclass', 'self'].each do |klass|
+    it "should raise an UndocumentableError for invalid class '#{klass}'" do
+      with_parser(:ruby18) { undoc_error "class #{klass}; end" }
+    end
+  end
+
+  ['@@INVALID', 'hi', '$MYCLASS', 'AnotherClass.new'].each do |klass|
+    it "should raise an UndocumentableError for invalid superclass '#{klass}' but it should create the class." do
+      YARD::CodeObjects::ClassObject.should_receive(:new).with(Registry.root, 'A')
+      with_parser(:ruby18) { undoc_error "class A < #{klass}; end" }
+      Registry.at('A').superclass.should == P(:Object)
+    end
+  end
+
+  ['not.aclass', 'self', 'AnotherClass.new'].each do |klass|
+    it "should raise an UndocumentableError if the constant class reference 'class << SomeConstant' does not point to a valid class name" do
+      with_parser(:ruby18) do
+        undoc_error <<-eof
+          CONST = #{klass}
+          class << CONST; end
+        eof
+      end
+      Registry.at(klass).should be_nil
+    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 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
+
+  it "should not overwrite docstring with an empty one" do
+    Registry.at(:Zebra).docstring.should == "Docstring 2"
+  end
+
+  it "should turn 'class Const < Struct.new(:sym)' into class Const with attr :sym" do
+    obj = Registry.at("Point")
+    obj.should be_kind_of(CodeObjects::ClassObject)
+    attrs = obj.attributes[:instance]
+    [:x, :y, :z].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 'class Const < Struct.new('Name', :sym)' into class Const with attr :sym" do
+    obj = Registry.at("AnotherPoint")
+    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
+
+    Registry.at("XPoint").should be_nil
+  end
+
+  it "should create a Struct::Name class when class Const < Struct.new('Name', :sym) is found" do
+    obj = Registry.at("Struct::XPoint")
+    obj.should_not be_nil
+  end
+
+  it "should attach attribtues to the generated Struct::Name class when Struct.new('Name') is used" do
+    obj = Registry.at("Struct::XPoint")
+    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 use @attr to set attribute descriptions on Struct subclasses" do
+    obj = Registry.at("DoccedStruct#input")
+    obj.docstring.should == "the input stream"
+  end
+
+  it "should use @attr to set attribute types on Struct subclasses" do
+    obj = Registry.at("DoccedStruct#someproc")
+    obj.should_not be_nil
+    obj.tag(:return).should_not be_nil
+    obj.tag(:return).types.should == ["Proc", "#call"]
+  end
+
+  it "should default types unspecified by @attr to Object on Struct subclasses" do
+    obj = Registry.at("DoccedStruct#mode")
+    obj.should_not be_nil
+    obj.tag(:return).should_not be_nil
+    obj.tag(:return).types.should == ["Object"]
+  end
+
+  it "should create parameters for writers of Struct subclass's attributes" do
+    obj = Registry.at("DoccedStruct#input=")
+    obj.tags(:param).size.should == 1
+    obj.tag(:param).types.should == ["IO"]
+  end
+
+  ["SemiDoccedStruct", "NotAStruct"].each do |struct|
+    describe("Attributes on a " + (struct == "NotAStruct" ? "class" : "struct")) do
+      it "defines both readers and writers when @attr is used on Structs" do
+        obj = Registry.at(struct)
+        attrs = obj.attributes[:instance]
+        attrs[:first][:read].should_not be_nil
+        attrs[:first][:write].should_not be_nil
+      end
+
+      it "defines only a reader when only @attr_reader is used on Structs" do
+        obj = Registry.at(struct)
+        attrs = obj.attributes[:instance]
+        attrs[:second][:read].should_not be_nil
+        attrs[:second][:write].should be_nil
+      end
+
+      it "defines only a writer when only @attr_writer is used on Structs" do
+        obj = Registry.at(struct)
+        attrs = obj.attributes[:instance]
+        attrs[:third][:read].should be_nil
+        attrs[:third][:write].should_not be_nil
+      end
+
+      it "defines a reader with correct return types when @attr_reader is used on Structs" do
+        obj = Registry.at("#{struct}#second")
+        obj.tag(:return).types.should == ["Fixnum"]
+      end
+
+      it "defines a writer with correct parameter types when @attr_writer is used on Structs" do
+        obj = Registry.at("#{struct}#third=")
+        obj.tag(:param).types.should == ["Array"]
+      end
+
+      it "defines a reader and a writer when both @attr_reader and @attr_writer are used" do
+        obj = Registry.at(struct)
+        attrs = obj.attributes[:instance]
+        attrs[:fourth][:read].should_not be_nil
+        attrs[:fourth][:write].should_not be_nil
+      end
+
+      it "uses @attr_reader for the getter when both @attr_reader and @attr_writer are given" do
+        obj = Registry.at("#{struct}#fourth")
+        obj.tag(:return).types.should == ["#read"]
+      end
+
+      it "uses @attr_writer for the setter when both @attr_reader and @attr_writer are given" do
+        obj = Registry.at("#{struct}#fourth=")
+        obj.tag(:param).types.should == ["IO"]
+      end
+
+      it "extracts text from @attr_reader" do
+        Registry.at("#{struct}#fourth").docstring.should == "returns a proc that reads"
+      end
+
+      it "extracts text from @attr_writer" do
+        Registry.at("#{struct}#fourth=").docstring.should == "sets the proc that writes stuff"
+      end
+    end
+  end
+
+  it "should inherit from a regular struct" do
+    Registry.at('RegularStruct').superclass.should == P(:Struct)
+    Registry.at('RegularStruct2').superclass.should == P(:Struct)
+  end
+
+  it "should handle inheritance from 'self'" do
+    Registry.at('Outer1::Inner1').superclass.should == Registry.at('Outer1')
+  end
+end

data/spec/handlers/class_variable_handler_spec.rb

@@ -0,0 +1,11 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}ClassVariableHandler" do
+  before(:all) { parse_file :class_variable_handler_001, __FILE__ }
+
+  it "should not parse class variables inside methods" do
+    obj = Registry.at("A::B::@@somevar")
+    obj.source.should == "@@somevar = \"hello\""
+    obj.value.should == '"hello"'
+  end
+end

data/spec/handlers/constant_handler_spec.rb

@@ -0,0 +1,64 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}ConstantHandler" do
+  before(:all) { 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
+
+  it "should maintain newlines" do
+    Registry.at("A::B::MYCONSTANT").value.gsub("\r", "").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 maintain docstrings on structs defined via constants" do
+    obj = Registry.at("DocstringStruct")
+    obj.should_not be_nil
+    obj.docstring.should == "A crazy struct."
+    obj.attributes[:instance].should_not be_empty
+    a1 = Registry.at("DocstringStruct#bar")
+    a2 = Registry.at("DocstringStruct#baz")
+    a1.docstring.should == "An attr"
+    a1.tag(:return).types.should == ["String"]
+    a2.docstring.should == "Another attr"
+    a2.tag(:return).types.should == ["Number"]
+  end
+
+  it "should raise undocumentable error in 1.9 parser for Struct.new assignment to non-const" do
+    undoc_error "nonconst = Struct.new"
+  end unless LEGACY_PARSER
+end