yard 0.7.5 → 0.8.0

data/spec/options_spec.rb

@@ -0,0 +1,160 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::Options do
+  class FooOptions < YARD::Options
+    attr_accessor :foo
+    def initialize; self.foo = "abc" end
+  end
+
+  describe '.default_attr' do
+    it "should allow default attributes to be defined with symbols" do
+      class DefaultOptions1 < YARD::Options
+        default_attr :foo, 'HELLO'
+      end
+      o = DefaultOptions1.new
+      o.reset_defaults
+      o.foo.should == 'HELLO'
+    end
+
+    it "should call lambda if value is a Proc" do
+      class DefaultOptions2 < YARD::Options
+        default_attr :foo, lambda { 100 }
+      end
+      o = DefaultOptions2.new
+      o.reset_defaults
+      o.foo.should == 100
+    end
+  end
+
+  describe '#reset_defaults' do
+    it "should not define defaults until reset is called" do
+      class ResetDefaultOptions1 < YARD::Options
+        default_attr :foo, 'FOO'
+      end
+      ResetDefaultOptions1.new.foo.should be_nil
+      o = ResetDefaultOptions1.new
+      o.reset_defaults
+      o.foo.should == 'FOO'
+    end
+  end
+
+  describe '#delete' do
+    it "should delete an option" do
+      o = FooOptions.new
+      o.delete(:foo)
+      o.to_hash.should == {}
+    end
+
+    it "should not error if an option is deleted that does not exist" do
+      o = FooOptions.new
+      o.delete(:foo)
+      o.delete(:foo)
+      o.to_hash.should == {}
+    end
+  end
+
+  describe '#[]' do
+    it "should handle getting option values using hash syntax" do
+      FooOptions.new[:foo].should == "abc"
+    end
+  end
+
+  describe '#[]=' do
+    it "should handle setting options using hash syntax" do
+      o = FooOptions.new
+      o[:foo] = "xyz"
+      o[:foo].should == "xyz"
+    end
+
+    it "should allow setting of unregistered keys" do
+      o = FooOptions.new
+      o[:bar] = "foo"
+      o[:bar].should == "foo"
+    end
+  end
+
+  describe '#method_missing' do
+    it "should allow setting of unregistered keys" do
+      o = FooOptions.new
+      o.bar = 'foo'
+      o.bar.should == 'foo'
+    end
+
+    it "should allow getting values of unregistered keys (return nil)" do
+      FooOptions.new.bar.should be_nil
+    end
+
+    it "should print debugging messages about unregistered keys" do
+      log.should_receive(:debug).with("Attempting to access unregistered key bar on FooOptions")
+      FooOptions.new.bar
+      log.should_receive(:debug).with("Attempting to set unregistered key bar on FooOptions")
+      FooOptions.new.bar = 1
+    end
+  end
+
+  describe '#update' do
+    it "should allow updating of options" do
+      FooOptions.new.update(:foo => "xyz").foo.should == "xyz"
+    end
+
+    it "should not ignore keys with no setter (OpenStruct behaviour)" do
+      o = FooOptions.new
+      o.update(:bar => "xyz")
+      o.to_hash.should == {:foo => "abc", :bar => "xyz"}
+    end
+  end
+
+  describe '#merge' do
+    it "should update a new object" do
+      o = FooOptions.new
+      o.merge(:foo => "xyz").object_id.should_not == o.object_id
+      o.merge(:foo => "xyz").to_hash.should == {:foo => "xyz"}
+    end
+
+    it "should add in values from original object" do
+      o = FooOptions.new
+      o.update(:bar => "foo")
+      o.merge(:baz => 1).to_hash.should == {:foo => "abc", :bar => "foo", :baz => 1}
+    end
+  end
+
+  describe '#to_hash' do
+    it "should convert all instance variables and symbolized keys" do
+      class ToHashOptions1 < YARD::Options
+        attr_accessor :foo, :bar, :baz
+        def initialize; @foo = 1; @bar = 2; @baz = "hello" end
+      end
+      o = ToHashOptions1.new
+      hash = o.to_hash
+      hash.keys.should include(:foo, :bar, :baz)
+      hash[:foo].should == 1
+      hash[:bar].should == 2
+      hash[:baz].should == "hello"
+    end
+
+    it "should use accessor when converting values to hash" do
+      class ToHashOptions2 < YARD::Options
+        def initialize; @foo = 1 end
+        def foo; "HELLO#{@foo}" end
+      end
+      o = ToHashOptions2.new
+      o.to_hash.should == {:foo => "HELLO1"}
+    end
+
+    it "should ignore ivars with no accessor" do
+      class ToHashOptions3 < YARD::Options
+        attr_accessor :foo
+        def initialize; @foo = 1; @bar = "NOIGNORE" end
+      end
+      o = ToHashOptions3.new
+      o.to_hash.should == {:foo => 1, :bar => "NOIGNORE"}
+    end
+  end
+
+  describe '#tap' do
+    it "should support #tap(&block) (even in 1.8.6)" do
+      o = FooOptions.new.tap {|o| o.foo = :BAR }
+      o.to_hash.should == {:foo => :BAR}
+    end
+  end
+end

data/spec/parser/base_spec.rb

@@ -3,12 +3,12 @@ require File.join(File.dirname(__FILE__), '..', 'spec_helper')
 describe YARD::Parser::Base do
   describe '#initialize' do
     class MyParser < Parser::Base; def initialize(a, b) end end
-    
+
     it "should take 2 arguments" do
-      lambda { YARD::Parser::Base.new }.should raise_error(ArgumentError, 
+      lambda { YARD::Parser::Base.new }.should raise_error(ArgumentError,
         /wrong (number|#) of arguments|given 0, expected 2/)
     end
-    
+
     it "should raise NotImplementedError on #initialize" do
       lambda { YARD::Parser::Base.new('a', 'b') }.should raise_error(NotImplementedError)
     end

data/spec/parser/c_parser_spec.rb

@@ -1,25 +1,16 @@
 require File.join(File.dirname(__FILE__), '..', 'spec_helper')
-begin require 'continuation'; rescue LoadError; end unless RUBY18
 
-class YARD::Parser::CParser; def ensure_loaded!(a, b=1) a end end
-
-describe YARD::Parser::CParser do
+describe YARD::Parser::C::CParser do
   describe '#parse' do
-    def parse(src = @contents)
-      YARD::Registry.clear
-      Parser::CParser.new(src).parse
-    end
-
-    def parse_init(src = @contents)
-      YARD::Registry.clear
-      Parser::CParser.new("void Init_Foo() {\n#{src}\n}").parse
+    def parse(contents)
+      Registry.clear
+      YARD.parse_string(contents, :c)
     end
 
     describe 'Array class' do
       before(:all) do
         file = File.join(File.dirname(__FILE__), 'examples', 'array.c.txt')
-        @parser = Parser::CParser.new(IO.read(file))
-        @parser.parse
+        parse(File.read(file))
       end
 
       it "should parse Array class" do
@@ -34,292 +25,75 @@ describe YARD::Parser::CParser do
         obj.tags(:overload).size.should > 1
       end
     end
-    
+
     describe 'Source located in extra files' do
       before(:all) do
         @multifile = File.join(File.dirname(__FILE__), 'examples', 'multifile.c.txt')
         @extrafile = File.join(File.dirname(__FILE__), 'examples', 'extrafile.c.txt')
         @contents = File.read(@multifile)
       end
-      
+
       it "should look for methods in extra files (if 'in' comment is found)" do
         extra_contents = File.read(@extrafile)
         File.should_receive(:read).with('extra.c').and_return(extra_contents)
-        parse
+        parse(@contents)
         Registry.at('Multifile#extra').docstring.should == 'foo'
       end
 
       it "should stop searching for extra source file gracefully if file is not found" do
         File.should_receive(:read).with('extra.c').and_raise(Errno::ENOENT)
         log.should_receive(:warn).with("Missing source file `extra.c' when parsing Multifile#extra")
-        parse
+        parse(@contents)
         Registry.at('Multifile#extra').docstring.should == ''
       end
     end
-    
+
     describe 'Foo class' do
       it 'should not include comments in docstring source' do
-        @contents = <<-eof
-          /* 
+        parse <<-eof
+          /*
            * Hello world
            */
           VALUE foo(VALUE x) {
             int value = x;
           }
-          
+
           void Init_Foo() {
             rb_define_method(rb_cFoo, "foo", foo, 1);
           }
         eof
-        parse
-        Registry.at('Foo#foo').source.gsub(/\s\s+/, ' ').should == 
+        Registry.at('Foo#foo').source.gsub(/\s\s+/, ' ').should ==
           "VALUE foo(VALUE x) { int value = x;\n}"
       end
     end
-    
-    describe 'Handling namespace parsing' do
-      it 'should track variable names defined under namespaces' do
-        @contents = <<-eof
-          void Init_Foo(void) {
-              mFoo = rb_define_module("Foo");
-              cBar = rb_define_class_under(mFoo, "Bar", rb_cObject);
-              rb_define_method(cBar, "foo", foo, 1);
-          }
-        eof
-        parse
-        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
-        @contents = <<-eof
-          void Init_Foo(void) {
-              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
-        parse
-        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
-        @contents = <<-eof
-          void Init_Foo(void) {
-              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
-        parse
-        Registry.at('Foo::Bar::Baz#foo').should_not be_nil
-      end
-    end
-    
-    describe 'Defining methods with source in other files' do
-      it "should look in another file for method" do
-        File.should_receive(:read).at_least(1).times.with('file.c').and_return(<<-eof)
-          /* FOO
-           */
-          VALUE foo(VALUE x) 
-          { }
-
-          /* BAR
-           */
-          VALUE bar(VALUE x) 
-          { }
-        eof
-        @contents = <<-eof
-          void Init_Foo() {
-            rb_define_method(rb_cFoo, "foo", foo, 1); /* in file.c */
-            rb_define_global_function("bar", bar, 1); /* in file.c */
-          }
-        eof
-        parse
-        Registry.at('Foo#foo').docstring.should == 'FOO'
-        Registry.at('Kernel#bar').docstring.should == 'BAR'
-      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
-        @contents = <<-eof
-          void Init_Foo() {
-            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
-        parse
-        Registry.at('Foo#foo').docstring.should == 'FOO'
-        Registry.at('Kernel#bar').docstring.should == 'BAR'
-      end
-    end
-    
-    describe 'Defining attributes' do
-      before do
-        Registry.clear
-      end
-      
-      def run(read, write, commented = nil)
-        @contents = <<-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
-        parse
-      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
-    
-    describe 'Defining constants' 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
+    describe 'Constant' do
+      it 'should not truncate docstring' do
         parse <<-eof
-          /* Document-const: FOO
-           * Foo bar!
-           */
-
-          void Init_Foo() {
-            mFoo = rb_define_module("Foo");
-            rb_define_const(mFoo, "FOO", ID2SYM(100));
+          #define MSK_DEADBEEF 0xdeadbeef
+          void
+          Init_Mask(void)
+          {
+              rb_cMask  = rb_define_class("Mask", rb_cObject);
+              /* 0xdeadbeef: This constant is frequently used to indicate a
+               * software crash or deadlock in embedded systems. */
+              rb_define_const(rb_cMask, "DEADBEEF", INT2FIX(MSK_DEADBEEF));
           }
         eof
-        foo = Registry.at('Foo::FOO')
-        foo.type.should == :constant
-        foo.docstring.should == 'Foo bar!'
-        foo.value.should == 'ID2SYM(100)'
-        foo.file.should == '(stdin)'
-      end
-
-      it "should use comment attached to declaration as fallback" do
-        parse_init <<-eof
-          mFoo = rb_define_module("Foo");
-          /* foobar! */
-          rb_define_const(mFoo, "FOO", ID2SYM(100));
-        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");
-          /* 100: foobar! */
-          rb_define_const(mFoo, "FOO", ID2SYM(100));
-        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");
-          /* 100\\:x\\:y: foobar:x! */
-          rb_define_const(mFoo, "FOO", ID2SYM(100));
-        eof
-        foo = Registry.at('Foo::FOO')
-        foo.value.should == '100:x:y'
-        foo.docstring.should == 'foobar:x!'
-      end
-    end
-    
-    describe 'Defining aliases' do
-      before do
-        Registry.clear
-      end
-      
-      it "should allow defining of aliases (rb_define_alias)" do
-        @contents = <<-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
-        parse
-        
-        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
-        @contents = <<-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
-        parse
-
-        Registry.at('Foo#foo').should be_reader
-        Registry.at('Foo#foo?').should be_is_alias
+        constant = Registry.at('Mask::DEADBEEF')
+        constant.value.should == '0xdeadbeef'
+        constant.docstring.should == "This constant is frequently used to indicate a\nsoftware crash or deadlock in embedded systems."
       end
     end
   end
 
-  describe '#find_override_comment' do
+  describe 'Override comments' do
     before(:all) do
+      Registry.clear
       override_file = File.join(File.dirname(__FILE__), 'examples', 'override.c.txt')
-      @override_parser = Parser::CParser.new(IO.read(override_file)).parse
+      @override_parser = YARD.parse_string(File.read(override_file), :c)
     end
-    
+
     it "should parse GMP::Z class" do
       z = YARD::Registry.at('GMP::Z')
       z.should_not be_nil