yard 0.7.5 → 0.8.0

data/spec/handlers/base_spec.rb

@@ -8,19 +8,19 @@ describe YARD::Handlers::Base 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 raise NotImplementedError if process is called on a class with no #process" do
       class TestNotImplementedHandler < Handlers::Base
       end
-    
+
       lambda { TestNotImplementedHandler.new(0, 0).process }.should raise_error(NotImplementedError)
     end
-  
+
     it "should allow multiple handles arguments" do
       Handlers::Base.should_receive(:inherited).once
       class TestHandler1 < Handlers::Base
@@ -39,7 +39,7 @@ describe YARD::Handlers::Base do
       TestHandler2.handlers.should == [:a, :b, :c]
     end
   end
-  
+
   describe 'transitive tags' do
     it "should add transitive tags to children" do
       Registry.clear
@@ -58,7 +58,7 @@ describe YARD::Handlers::Base do
       Registry.at('A#bar').tag(:author).should be_nil
     end
   end
-  
+
   describe 'sharing global state' do
     it "should allow globals to share global state among handlers" do
       class GlobalStateHandler1 < Handlers::Ruby::Base
@@ -80,13 +80,13 @@ describe YARD::Handlers::Base do
       end
     end
   end if HAVE_RIPPER
-  
+
   describe '#push_state' do
     def process(klass)
       state = OpenStruct.new(:namespace => "ROOT", :scope => :instance, :owner => "ROOT")
       klass.new(state, nil).process
     end
-    
+
     it "should push and return all old state info after block" do
       class PushStateHandler1 < Handlers::Base
         def process
@@ -102,7 +102,7 @@ describe YARD::Handlers::Base do
       end
       process PushStateHandler1
     end
-    
+
     it "should allow owner to be pushed individually" do
       class PushStateHandler2 < Handlers::Base
         def process
@@ -116,7 +116,7 @@ describe YARD::Handlers::Base do
       end
       process PushStateHandler2
     end
-    
+
     it "should allow scope to be pushed individually" do
       class PushStateHandler3 < Handlers::Base
         def process
@@ -131,14 +131,14 @@ describe YARD::Handlers::Base do
       process PushStateHandler3
     end
   end
-  
+
   describe '.in_file' do
     def parse(filename, parser_type, src = "class A; end")
       parser = Parser::SourceParser.new(parser_type)
       parser.instance_variable_set("@file", filename)
       parser.parse(StringIO.new(src))
     end
-    
+
     def create_handler(stmts, parser_type)
       $handler_counter ||= 0
       sklass = parser_type == :ruby ? "Base" : "Legacy::Base"
@@ -150,7 +150,7 @@ describe YARD::Handlers::Base do
         end
       eof
     end
-    
+
     def test_handler(file, stmts, creates = true, parser_type = :ruby)
       Registry.clear
       Registry.at('#FOO').should be_nil
@@ -159,14 +159,14 @@ describe YARD::Handlers::Base do
       Registry.at('#FOO').send(creates ? :should_not : :should, be_nil)
       Handlers::Base.subclasses.delete_if {|k,v| k.to_s =~ /^InFileHandler/ }
     end
-    
+
     [:ruby, :ruby18].each do |parser_type|
       next if parser_type == :ruby && LEGACY_PARSER
       describe "Parser type = #{parser_type.inspect}" do
         it "should allow handler to be specific to a file" do
           test_handler 'file_a.rb', 'in_file "file_a.rb"', true, parser_type
         end
-    
+
         it "should ignore handler if filename does not match" do
           test_handler 'file_b.rb', 'in_file "file_a.rb"', false, parser_type
         end
@@ -174,7 +174,7 @@ describe YARD::Handlers::Base do
         it "should only test filename part when given a String" do
           test_handler '/path/to/file_a.rb', 'in_file "/to/file_a.rb"', false, parser_type
         end
-    
+
         it "should test exact match for entire String" do
           test_handler 'file_a.rb', 'in_file "file"', false, parser_type
         end

data/spec/handlers/c/alias_handler_spec.rb

@@ -0,0 +1,33 @@
+require File.dirname(__FILE__) + "/spec_helper"
+
+describe YARD::Handlers::C::AliasHandler do
+  it "should allow defining of aliases (rb_define_alias)" do
+    parse <<-eof
+      /* FOO */
+      VALUE foo(VALUE x) { int value = x; }
+      void Init_Foo() {
+        rb_cFoo = rb_define_class("Foo", rb_cObject);
+        rb_define_method(rb_cFoo, "foo", foo, 1);
+        rb_define_alias(rb_cFoo, "bar", "foo");
+      }
+    eof
+
+    Registry.at('Foo#bar').should be_is_alias
+    Registry.at('Foo#bar').docstring.should == 'FOO'
+  end
+
+  it "should allow defining of aliases (rb_define_alias) of attributes" do
+    parse <<-eof
+      /* FOO */
+      VALUE foo(VALUE x) { int value = x; }
+      void Init_Foo() {
+        rb_cFoo = rb_define_class("Foo", rb_cObject);
+        rb_define_attr(rb_cFoo, "foo", 1, 0);
+        rb_define_alias(rb_cFoo, "foo?", "foo");
+      }
+    eof
+
+    Registry.at('Foo#foo').should be_reader
+    Registry.at('Foo#foo?').should be_is_alias
+  end
+end

data/spec/handlers/c/attribute_handler_spec.rb

@@ -0,0 +1,40 @@
+require File.dirname(__FILE__) + "/spec_helper"
+
+describe YARD::Handlers::C::AttributeHandler do
+  def run(read, write, commented = nil)
+    parse <<-eof
+      /* FOO */
+      VALUE foo(VALUE x) { int value = x; }
+      void Init_Foo() {
+        rb_cFoo = rb_define_class("Foo", rb_cObject);
+        #{commented ? '/*' : ''}
+          rb_define_attr(rb_cFoo, "foo", #{read}, #{write});
+        #{commented ? '*/' : ''}
+      }
+    eof
+  end
+
+  it "should handle readonly attribute (rb_define_attr)" do
+    run(1, 0)
+    Registry.at('Foo#foo').should be_reader
+    Registry.at('Foo#foo=').should be_nil
+  end
+
+  it "should handle writeonly attribute (rb_define_attr)" do
+    run(0, 1)
+    Registry.at('Foo#foo').should be_nil
+    Registry.at('Foo#foo=').should be_writer
+  end
+
+  it "should handle readwrite attribute (rb_define_attr)" do
+    run(1, 1)
+    Registry.at('Foo#foo').should be_reader
+    Registry.at('Foo#foo=').should be_writer
+  end
+
+  it "should handle commented writeonly attribute (/* rb_define_attr */)" do
+    run(1, 1, true)
+    Registry.at('Foo#foo').should be_reader
+    Registry.at('Foo#foo=').should be_writer
+  end
+end

data/spec/handlers/c/class_handler_spec.rb

@@ -0,0 +1,64 @@
+require File.dirname(__FILE__) + "/spec_helper"
+
+describe YARD::Handlers::C::ClassHandler do
+  it "should register classes" do
+    parse_init 'cFoo = rb_define_class("Foo", rb_cObject);'
+    Registry.at('Foo').type.should == :class
+  end
+
+  it "should register classes under namespaces" do
+    parse_init 'cFoo = rb_define_class_under(cBar, "Foo", rb_cObject);'
+    Registry.at('Bar::Foo').type.should == :class
+  end
+
+  it "should remember symbol defined with class" do
+    parse_init(<<-eof)
+      cXYZ = rb_define_class("Foo", rb_cObject);
+      rb_define_method(cXYZ, "bar", bar, 0);
+    eof
+    Registry.at('Foo').type.should == :class
+    Registry.at('Foo#bar').should_not be_nil
+  end
+
+  it "should lookup superclass symbol name" do
+    parse_init(<<-eof)
+      cXYZ = rb_define_class("Foo", rb_cObject);
+      cBar = rb_define_class("Bar", cXYZ);
+    eof
+    Registry.at('Bar').superclass.should == Registry.at('Foo')
+  end
+
+  it "should user superclass symbol name as proxy if not found" do
+    parse_init(<<-eof)
+      // cXYZ = rb_define_class("Foo", rb_cObject);
+      cBar = rb_define_class("Bar", cXYZ);
+    eof
+    Registry.at('Bar').superclass.should == P('XYZ')
+  end
+
+  it "should not associate declaration comments as class docstring" do
+    parse_init(<<-eof)
+      /* Docstring! */
+      cFoo = rb_define_class("Foo", cObject);
+    eof
+    Registry.at('Foo').docstring.should be_blank
+  end
+
+  it "should associate a file with the declaration" do
+    parse_init(<<-eof)
+      cFoo = rb_define_class("Foo", cObject);
+    eof
+    Registry.at('Foo').file.should == '(stdin)'
+    Registry.at('Foo').line.should == 2
+  end
+
+  it "should properly handle Proxy superclasses" do
+    parse_init <<-eof
+      cFoo = rb_define_class_under(mFoo, "Bar", rb_cBar);
+    eof
+    Registry.at('Foo::Bar').type.should == :class
+    Registry.at('Foo::Bar').superclass.should == P('Bar')
+    P('Bar').should be_a(CodeObjects::Proxy)
+    P('Bar').type.should == :class
+  end
+end

data/spec/handlers/c/constant_handler_spec.rb

@@ -0,0 +1,68 @@
+require File.dirname(__FILE__) + "/spec_helper"
+
+describe YARD::Handlers::C::ConstantHandler do
+  it "should register constants" do
+    parse_init <<-eof
+      mFoo = rb_define_module("Foo");
+      rb_define_const(mFoo, "FOO", ID2SYM(100));
+    eof
+    Registry.at('Foo::FOO').type.should == :constant
+  end
+
+  it "should look for override comments" do
+    parse <<-eof
+      /* Document-const: FOO
+       * Document-const: Foo::BAR
+       * Foo bar!
+       */
+
+      void Init_Foo() {
+        mFoo = rb_define_module("Foo");
+        rb_define_const(mFoo, "FOO", ID2SYM(100));
+        rb_define_const(mFoo, "BAR", ID2SYM(101));
+      }
+    eof
+    foo = Registry.at('Foo::FOO')
+    foo.type.should == :constant
+    foo.docstring.should == 'Foo bar!'
+    foo.value.should == 'ID2SYM(100)'
+    foo.file.should == '(stdin)'
+    foo.line.should == 8
+    bar = Registry.at('Foo::BAR')
+    bar.type.should == :constant
+    bar.docstring.should == 'Foo bar!'
+    bar.file.should == '(stdin)'
+    bar.line.should == 9
+    bar.value.should == 'ID2SYM(101)'
+  end
+
+  it "should use comment attached to declaration as fallback" do
+    parse_init <<-eof
+      mFoo = rb_define_module("Foo");
+      rb_define_const(mFoo, "FOO", ID2SYM(100)); // foobar!
+    eof
+    foo = Registry.at('Foo::FOO')
+    foo.value.should == 'ID2SYM(100)'
+    foo.docstring.should == 'foobar!'
+  end
+
+  it "should allow the form VALUE: DOCSTRING to document value" do
+    parse_init <<-eof
+      mFoo = rb_define_module("Foo");
+      rb_define_const(mFoo, "FOO", ID2SYM(100)); // 100: foobar!
+    eof
+    foo = Registry.at('Foo::FOO')
+    foo.value.should == '100'
+    foo.docstring.should == 'foobar!'
+  end
+
+  it "should allow escaping of backslashes in VALUE: DOCSTRING syntax" do
+    parse_init <<-eof
+      mFoo = rb_define_module("Foo");
+      rb_define_const(mFoo, "FOO", ID2SYM(100)); // 100\\:x\\:y: foobar:x!
+    eof
+    foo = Registry.at('Foo::FOO')
+    foo.value.should == '100:x:y'
+    foo.docstring.should == 'foobar:x!'
+  end
+end

data/spec/handlers/c/init_handler_spec.rb

@@ -0,0 +1,36 @@
+require File.dirname(__FILE__) + "/spec_helper"
+
+describe YARD::Handlers::C::InitHandler do
+  it "should add documentation in Init_ClassName() to ClassName" do
+    parse(<<-eof)
+      // Bar!
+      void Init_A() {
+        rb_cA = rb_define_class("A", rb_cObject);
+      }
+    eof
+    Registry.at('A').docstring.should == 'Bar!'
+  end
+
+  it "should not add documentation if ClassName is not created in Init" do
+    parse(<<-eof)
+      // Bar!
+      void Init_A() {
+      }
+    eof
+    Registry.at('A').should be_nil
+  end
+
+  it "should not overwrite override comment" do
+    parse(<<-eof)
+      /* Document-class: A
+       * Foo!
+       */
+
+      // Bar!
+      void Init_A() {
+        rb_cA = rb_define_class("A", rb_cObject);
+      }
+    eof
+    Registry.at('A').docstring.should == 'Foo!'
+  end
+end

data/spec/handlers/c/method_handler_spec.rb

@@ -0,0 +1,228 @@
+require File.dirname(__FILE__) + "/spec_helper"
+
+describe YARD::Handlers::C::MethodHandler do
+  it "should register methods" do
+    parse_init <<-eof
+      mFoo = rb_define_module("Foo");
+      rb_define_method(mFoo, "bar", bar, 0);
+    eof
+    Registry.at('Foo#bar').should_not be_nil
+    Registry.at('Foo#bar').visibility.should == :public
+  end
+
+  it "should register private methods" do
+    parse_init <<-eof
+      mFoo = rb_define_module("Foo");
+      rb_define_private_method(mFoo, "bar", bar, 0);
+    eof
+    Registry.at('Foo#bar').should_not be_nil
+    Registry.at('Foo#bar').visibility.should == :private
+  end
+
+  it "should register singleton methods" do
+    parse_init <<-eof
+      mFoo = rb_define_module("Foo");
+      rb_define_singleton_method(mFoo, "bar", bar, 0);
+    eof
+    Registry.at('Foo.bar').should_not be_nil
+    Registry.at('Foo.bar').visibility.should == :public
+  end
+
+  it "should register module functions" do
+    parse <<-eof
+      /* DOCSTRING
+       * @return [String] foo!
+      */
+      static VALUE bar(VALUE self) { x(); y(); z(); }
+
+      void Init_Foo() {
+        mFoo = rb_define_module("Foo");
+        rb_define_module_function(mFoo, "bar", bar, 0);
+      }
+    eof
+    bar_c = Registry.at('Foo.bar')
+    bar_i = Registry.at('Foo#bar')
+    bar_c.should be_module_function
+    bar_c.visibility.should == :public
+    bar_c.docstring.should == "DOCSTRING"
+    bar_c.tag(:return).object.should == bar_c
+    bar_c.source.should == "static VALUE bar(VALUE self) { x(); y(); z(); }"
+    bar_i.should_not be_module_function
+    bar_i.visibility.should == :private
+    bar_i.docstring.should == "DOCSTRING"
+    bar_i.tag(:return).object.should == bar_i
+    bar_i.source.should == bar_c.source
+  end
+
+  it "should register global functions into Kernel" do
+    parse_init 'rb_define_global_function("bar", bar, 0);'
+    Registry.at('Kernel#bar').should_not be_nil
+  end
+
+  it "should look for symbol containing method source" do
+    parse <<-eof
+      static VALUE foo(VALUE self) { x(); y(); z(); }
+      VALUE bar() { a(); b(); c(); }
+      void Init_Foo() {
+        mFoo = rb_define_module("Foo");
+        rb_define_method(mFoo, "foo", foo, 0);
+        rb_define_method(mFoo, "bar", bar, 0);
+      }
+    eof
+    foo = Registry.at('Foo#foo')
+    bar = Registry.at('Foo#bar')
+    foo.source.should == "static VALUE foo(VALUE self) { x(); y(); z(); }"
+    foo.file.should == '(stdin)'
+    foo.line.should == 1
+    bar.source.should == "VALUE bar() { a(); b(); c(); }"
+    bar.file.should == '(stdin)'
+    bar.line.should == 2
+  end
+
+  it "should find docstrings attached to method symbols" do
+    parse <<-eof
+      /* DOCSTRING */
+      static VALUE foo(VALUE self) { x(); y(); z(); }
+      void Init_Foo() {
+        mFoo = rb_define_module("Foo");
+        rb_define_method(mFoo, "foo", foo, 0);
+      }
+    eof
+    foo = Registry.at('Foo#foo')
+    foo.docstring.should == 'DOCSTRING'
+  end
+
+  it "should use declaration comments as docstring if there are no others" do
+    parse <<-eof
+      static VALUE foo(VALUE self) { x(); y(); z(); }
+      void Init_Foo() {
+        mFoo = rb_define_module("Foo");
+        /* DOCSTRING */
+        rb_define_method(mFoo, "foo", foo, 0);
+        // DOCSTRING!
+        rb_define_method(mFoo, "bar", bar, 0);
+      }
+    eof
+    foo = Registry.at('Foo#foo')
+    foo.docstring.should == 'DOCSTRING'
+    bar = Registry.at('Foo#bar')
+    bar.docstring.should == 'DOCSTRING!'
+  end
+
+  it "should look for symbols in other file" do
+    other = <<-eof
+      /* DOCSTRING! */
+      static VALUE foo() { x(); }
+    eof
+    File.should_receive(:read).with('other.c').and_return(other)
+    parse <<-eof
+      void Init_Foo() {
+        mFoo = rb_define_module("Foo");
+        rb_define_method(mFoo, "foo", foo, 0); // in other.c
+      }
+    eof
+    foo = Registry.at('Foo#foo')
+    foo.docstring.should == 'DOCSTRING!'
+    foo.file.should == 'other.c'
+    foo.line.should == 2
+    foo.source.should == 'static VALUE foo() { x(); }'
+  end
+
+  it "should allow extra file to include /'s and other filename characters" do
+    File.should_receive(:read).at_least(1).times.with('ext/a-file.c').and_return(<<-eof)
+      /* FOO */
+      VALUE foo(VALUE x) { int value = x; }
+
+      /* BAR */
+      VALUE bar(VALUE x) { int value = x; }
+    eof
+    parse_init <<-eof
+      rb_define_method(rb_cFoo, "foo", foo, 1); /* in ext/a-file.c */
+      rb_define_global_function("bar", bar, 1); /* in ext/a-file.c */
+    eof
+    Registry.at('Foo#foo').docstring.should == 'FOO'
+    Registry.at('Kernel#bar').docstring.should == 'BAR'
+  end
+
+  it "should warn if other file can't be found" do
+    log.should_receive(:warn).with(/Missing source file `other.c' when parsing Foo#foo/)
+    parse <<-eof
+      void Init_Foo() {
+        mFoo = rb_define_module("Foo");
+        rb_define_method(mFoo, "foo", foo, 0); // in other.c
+      }
+    eof
+  end
+
+  it "should look at override comments for docstring" do
+    parse <<-eof
+      /* Document-method: Foo::foo
+       * Document-method: new
+       * Document-method: Foo::Bar#baz
+       * Foo bar!
+       */
+
+      // init comments
+      void Init_Foo() {
+        mFoo = rb_define_module("Foo");
+        rb_define_method(mFoo, "foo", foo, 0);
+        rb_define_method(mFoo, "initialize", foo, 0);
+        mBar = rb_define_module_under(mFoo, "Bar");
+        rb_define_method(mBar, "baz", foo, 0);
+      }
+    eof
+    Registry.at('Foo#foo').docstring.should == 'Foo bar!'
+    Registry.at('Foo#initialize').docstring.should == 'Foo bar!'
+    Registry.at('Foo::Bar#baz').docstring.should == 'Foo bar!'
+  end
+
+  it "should look at overrides in other files" do
+    other = <<-eof
+      /* Document-method: Foo::foo
+       * Document-method: new
+       * Document-method: Foo::Bar#baz
+       * Foo bar!
+       */
+    eof
+    File.should_receive(:read).with('other.c').and_return(other)
+    parse <<-eof
+      void Init_Foo() {
+        mFoo = rb_define_module("Foo");
+        rb_define_method(mFoo, "foo", foo, 0); // in other.c
+        rb_define_method(mFoo, "initialize", foo, 0); // in other.c
+        mBar = rb_define_module_under(mFoo, "Bar"); // in other.c
+        rb_define_method(mBar, "baz", foo, 0); // in other.c
+      }
+    eof
+    Registry.at('Foo#foo').docstring.should == 'Foo bar!'
+    Registry.at('Foo#initialize').docstring.should == 'Foo bar!'
+    Registry.at('Foo::Bar#baz').docstring.should == 'Foo bar!'
+  end
+
+  it "should add return tag on methods ending in '?'" do
+    parse <<-eof
+      /* DOCSTRING */
+      static VALUE foo(VALUE self) { x(); y(); z(); }
+      void Init_Foo() {
+        mFoo = rb_define_module("Foo");
+        rb_define_method(mFoo, "foo?", foo, 0);
+      }
+    eof
+    foo = Registry.at('Foo#foo?')
+    foo.docstring.should == 'DOCSTRING'
+    foo.tag(:return).types.should == ['Boolean']
+  end
+
+  it "should not add return tag if return tags exist" do
+    parse <<-eof
+      // @return [String] foo
+      static VALUE foo(VALUE self) { x(); y(); z(); }
+      void Init_Foo() {
+        mFoo = rb_define_module("Foo");
+        rb_define_method(mFoo, "foo?", foo, 0);
+      }
+    eof
+    foo = Registry.at('Foo#foo?')
+    foo.tag(:return).types.should == ['String']
+  end
+end