yard 0.6.8 → 0.7.0

data/spec/handlers/base_spec.rb

@@ -59,6 +59,28 @@ describe YARD::Handlers::Base do
     end
   end
   
+  describe 'sharing global state' do
+    it "should allow globals to share global state among handlers" do
+      class GlobalStateHandler1 < Handlers::Ruby::Base
+        class << self; attr_accessor :state end
+        handles :class
+        process { self.class.state = globals.foo; globals.foo = :bar }
+      end
+
+      class GlobalStateHandler2 < Handlers::Ruby::Base
+        class << self; attr_accessor :state end
+        handles :def
+        process { self.class.state = globals.foo }
+      end
+
+      2.times do
+        YARD.parse_string 'class Foo; end; def foo; end'
+        GlobalStateHandler1.state.should == nil
+        GlobalStateHandler2.state.should == :bar
+      end
+    end
+  end if HAVE_RIPPER
+  
   describe '#push_state' do
     def process(klass)
       state = OpenStruct.new(:namespace => "ROOT", :scope => :instance, :owner => "ROOT")

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

@@ -0,0 +1,73 @@
+class Foo
+  attr_accessor :ignoreme
+
+  # IMPLICIT METHOD!
+  # @return [String]
+  just_a_method_for :implicit0
+  
+  # Not recognized
+  just_a_method_for :implicit_invalid
+  
+  #
+  ## IS NOT RECOGNIZED!
+  just_a_method_for :implicit_invalid2
+
+  ##
+  # IS RECOGNIZED!
+  just_a_method_for 'implicit_valid'
+
+  # @attribute [r]
+  # @return [Numeric] a number
+  a_readable_attribute :attr1
+  
+  # @attribute [w]
+  a_writable_attribute :attr2, 'bar'
+
+  # @attribute
+  default_attribute :attr3
+  
+  # @method xyz(a, b, c)
+  # The foo method
+  # @param [String] a
+  # @visibility protected
+  # @scope class
+  foo_bar
+
+  # @macro property
+  # @method $1(${3-})
+  # A $0 that is awesome.
+  # @param $3 first parameter
+  # @return [$2] the property $1
+  property :name, String, :a, :b, :c
+  
+  # @macro property
+  property :age, Fixnum, :value
+  
+  # This is just for x
+  # @macro [attach] parser
+  #   @method $1(opts = {})
+  #   @return NOTHING!
+  parser :x
+  
+  parser :c_parser
+  
+  # @macro [attach] none
+  # @method none(foo, bar)
+  none
+  
+  # @macro something
+  # @overload $1(a, b, c)
+  something :qux
+  
+  # @overload qux2(a, b, c)
+  something
+end
+
+class Bar
+  parser :x_parser
+end
+
+class Baz < Foo
+  parser :y_parser
+  none { }
+end

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

@@ -91,3 +91,20 @@ class D
   # 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

data/spec/handlers/macro_handler_spec.rb

@@ -0,0 +1,140 @@
+require File.dirname(__FILE__) + '/spec_helper'
+require 'ostruct'
+
+describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}MacroHandler" do
+  before(:all) { parse_file :macro_handler_001, __FILE__ }
+  
+  it "should create a readable attribute when @attribute r is found" do
+    obj = Registry.at('Foo#attr1')
+    obj.should_not be_nil
+    obj.should be_reader
+    obj.tag(:return).types.should == ['Numeric']
+    Registry.at('Foo#attr1=').should be_nil
+  end
+
+  it "should create a writable attribute when @attribute w is found" do
+    obj = Registry.at('Foo#attr2=')
+    obj.should_not be_nil
+    obj.should be_writer
+    Registry.at('Foo#attr2').should be_nil
+  end
+  
+  it "should default to readwrite @attribute" do
+    obj = Registry.at('Foo#attr3')
+    obj.should_not be_nil
+    obj.should be_reader
+    obj = Registry.at('Foo#attr3=')
+    obj.should_not be_nil
+    obj.should be_writer
+  end
+
+  it "should default to creating an instance method for any DSL method with tags" do
+    obj = Registry.at('Foo#implicit0')
+    obj.should_not be_nil
+    obj.docstring.should == "IMPLICIT METHOD!"
+    obj.tag(:return).types.should == ['String']
+  end
+  
+  it "should set the method name when using @method" do
+    obj = Registry.at('Foo.xyz')
+    obj.should_not be_nil
+    obj.signature.should == 'def xyz(a, b, c)'
+    obj.source.should == 'foo_bar'
+    obj.docstring.should == 'The foo method'
+  end
+  
+  it "should create hidden overlaod tag when @method has signature" do
+    obj = Registry.at('Foo.xyz')
+    obj.docstring.tag(:overload).signature.should == 'xyz(a, b, c)'
+    obj.docstring.tag(:overload).object.should == obj
+  end
+  
+  it "should set the method name when using @overload" do
+    obj = Registry.at('Foo#qux2')
+    obj.should_not be_nil
+    obj.signature.should == 'def qux2(a, b, c)'
+    obj.source.should == 'something'
+    obj.docstring.tag(:overload).name.should == :qux2
+    obj.docstring.tag(:overload).object.should == obj
+  end
+
+  it "should set the method object when using @overload" do
+    obj = Registry.at('Foo#qux')
+    obj.should_not be_nil
+    obj.signature.should == 'def qux(a, b, c)'
+    obj.source.should == 'something :qux'
+    obj.docstring.tag(:overload).name.should == :qux
+    obj.docstring.tag(:overload).object.should == obj
+  end
+  
+  it "should allow setting of @scope" do
+    Registry.at('Foo.xyz').scope.should == :class
+  end
+  
+  it "should allow setting of @visibility" do
+    Registry.at('Foo.xyz').visibility.should == :protected
+  end
+  
+  it "should ignore DSL methods without tags" do
+    Registry.at('Foo#implicit_invalid').should be_nil
+  end
+
+  it "should accept a DSL method without tags if it has hash_flag (##)" do
+    Registry.at('Foo#implicit_valid').should_not be_nil
+    Registry.at('Foo#implicit_invalid2').should be_nil
+  end
+ 
+  it "should allow creation of macros" do
+    macro = CodeObjects::MacroObject.find('property')
+    macro.should_not be_nil
+    macro.should_not be_attached
+    macro.method_object.should be_nil
+  end
+  
+  it "should handle macros with no parameters to expand" do
+    Registry.at('Foo#none').should_not be_nil
+    Registry.at('Baz#none').signature.should == 'def none(foo, bar)'
+  end
+  
+  it "should apply new macro docstrings on new objects" do
+    obj = Registry.at('Foo#name')
+    obj.should_not be_nil
+    obj.source.should == 'property :name, String, :a, :b, :c'
+    obj.signature.should == 'def name(a, b, c)'
+    obj.docstring.should == 'A property that is awesome.'
+    obj.tag(:param).name.should == 'a'
+    obj.tag(:param).text.should == 'first parameter'
+    obj.tag(:return).types.should == ['String']
+    obj.tag(:return).text.should == 'the property name'
+  end
+  
+  it "should allow reuse of named macros" do
+    obj = Registry.at('Foo#age')
+    obj.should_not be_nil
+    obj.source.should == 'property :age, Fixnum, :value'
+    obj.signature.should == 'def age(value)'
+    obj.docstring.should == 'A property that is awesome.'
+    obj.tag(:param).name.should == 'value'
+    obj.tag(:param).text.should == 'first parameter'
+    obj.tag(:return).types.should == ['Fixnum']
+    obj.tag(:return).text.should == 'the property age'
+  end
+  
+  it "should use implicitly named macros" do
+    macro = CodeObjects::MacroObject.find('parser')
+    macro.macro_data.should == "@method $1(opts = {})\n@return NOTHING!"
+    macro.should_not be_nil
+    macro.should be_attached
+    macro.method_object.should == P('Foo.parser')
+    obj = Registry.at('Foo#c_parser')
+    obj.should_not be_nil
+    obj.docstring.should == ""
+    obj.signature.should == "def c_parser(opts = {})"
+    obj.docstring.tag(:return).text.should == "NOTHING!"
+  end
+  
+  it "should only use implicit macros on methods defined in inherited hierarchy" do
+    Registry.at('Bar#x_parser').should be_nil
+    Registry.at('Baz#y_parser').should_not be_nil
+  end
+end

data/spec/handlers/method_handler_spec.rb

@@ -138,4 +138,32 @@ describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}MethodHandler"
     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.+macro name.+Foo\.foo/)
+    YARD.parse_string "class Foo\n# @macro\ndef self.foo; end\nend"
+  end
 end

data/spec/handlers/processor_spec.rb

@@ -16,4 +16,8 @@ describe YARD::Handlers::Processor do
   it "should start in root namespace" do
     @proc.namespace.should == Registry.root
   end
+  
+  it "should have a globals structure" do
+    @proc.globals.should be_a(OpenStruct)
+  end
 end

data/spec/handlers/spec_helper.rb

@@ -27,7 +27,7 @@ end
 class StubbedSourceParser < Parser::SourceParser
   StubbedSourceParser.parser_type = :ruby
   def post_process
-    post = StubbedProcessor.new(@file, @load_order_errors, @parser_type)
+    post = StubbedProcessor.new(@file, @load_order_errors, @parser_type, @globals)
     post.process(@parser.enumerator)
   end
 end

data/spec/parser/c_parser_spec.rb

@@ -2,29 +2,60 @@ require File.join(File.dirname(__FILE__), '..', 'spec_helper')
 begin require 'continuation'; rescue LoadError; end unless RUBY18
 
 describe YARD::Parser::CParser do
-  before(:all) do
-    file = File.join(File.dirname(__FILE__), 'examples', 'array.c.txt')
-    @parser = Parser::CParser.new(IO.read(file)).parse
-
-    override_file = File.join(File.dirname(__FILE__), 'examples', 'override.c.txt')
-    @override_parser = Parser::CParser.new(IO.read(override_file)).parse
-  end
-  
   describe '#parse' do
-    it "should parse Array class" do
-      obj = YARD::Registry.at('Array')
-      obj.should_not be_nil
-      obj.docstring.should_not be_blank
+    before(:all) do
+      file = File.join(File.dirname(__FILE__), 'examples', 'array.c.txt')
+      @parser = Parser::CParser.new(IO.read(file)).parse
+    end
+
+    describe 'Array class' do
+      it "should parse Array class" do
+        obj = YARD::Registry.at('Array')
+        obj.should_not be_nil
+        obj.docstring.should_not be_blank
+      end
+
+      it "should parse method" do
+        obj = YARD::Registry.at('Array#initialize')
+        obj.docstring.should_not be_blank
+        obj.tags(:overload).size.should > 1
+      end
     end
     
-    it "should parse method" do
-      obj = YARD::Registry.at('Array#initialize')
-      obj.docstring.should_not be_blank
-      obj.tags(:overload).size.should > 1
+    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
+      
+      def parse
+        Registry.clear
+        Parser::CParser.new(@contents).parse
+      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
+        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
+        Registry.at('Multifile#extra').docstring.should == ''
+      end
     end
   end
 
   describe '#find_override_comment' do
+    before(:all) do
+      override_file = File.join(File.dirname(__FILE__), 'examples', 'override.c.txt')
+      @override_parser = Parser::CParser.new(IO.read(override_file)).parse
+    end
+    
     it "should parse GMP::Z class" do
       z = YARD::Registry.at('GMP::Z')
       z.should_not be_nil

data/spec/parser/examples/extrafile.c.txt

@@ -0,0 +1,8 @@
+/* 
+ * foo
+ */
+VALUE
+rb_extra(VALUE obj, VALUE n)
+{
+  return Qtrue;
+}

data/spec/parser/examples/multifile.c.txt

@@ -0,0 +1,6 @@
+void
+Init_Multifile(void)
+{
+    rb_cMultifile  = rb_define_class("Multifile", rb_cObject);
+    rb_define_method(rb_cMultifile, "extra", rb_extra, 1); /* in extra.c */
+}

data/spec/parser/ruby/ruby_parser_spec.rb

@@ -198,5 +198,10 @@ describe YARD::Parser::Ruby::RubyParser do
       src = '("this is a string")'
       stmt(src).jump(:string_literal).source.should == '"this is a string"'
     end
+    
+    it "should show proper source for %w() array" do
+      src = "%w(\na b c\n d e f\n)"
+      stmt(src).jump(:qwords_literal).source.should == src
+    end
   end
 end if HAVE_RIPPER

data/spec/parser/source_parser_spec.rb

@@ -14,6 +14,201 @@ describe YARD::Parser::SourceParser do
     Registry.clear
   end
   
+  def parse_list(*list)
+    files = list.map do |v|
+      filename, source = *v
+      File.stub!(:read_binary).with(filename).and_return(source)
+      filename
+    end
+    Parser::SourceParser.send(:parse_in_order, *files)
+  end
+
+  def before_list(&block)
+    Parser::SourceParser.before_parse_list(&block)
+  end
+
+  def after_list(&block)
+    Parser::SourceParser.after_parse_list(&block)
+  end
+
+  def before_file(&block)
+    Parser::SourceParser.before_parse_file(&block)
+  end
+
+  def after_file(&block)
+    Parser::SourceParser.after_parse_file(&block)
+  end
+  
+  describe '.before_parse_list' do
+    before do
+      Parser::SourceParser.before_parse_list_callbacks.clear
+      Parser::SourceParser.after_parse_list_callbacks.clear
+    end
+
+    it "should handle basic callback support" do
+      before_list do |files, globals|
+        files.should == ['foo.rb', 'bar.rb']
+        globals.should == OpenStruct.new
+      end
+      parse_list ['foo.rb', 'foo!'], ['bar.rb', 'class Foo; end']
+      Registry.at('Foo').should_not be_nil
+    end
+    
+    it "should support multiple callbacks" do
+      checks = []
+      before_list { checks << :one }
+      before_list { checks << :two }
+      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
+      Registry.at('Foo').should_not be_nil  
+      checks.should == [:one, :two]
+    end
+    
+    it "should cancel parsing if it returns false" do
+      checks = []
+      before_list { checks << :one }
+      before_list { false }
+      before_list { checks << :three }
+      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
+      Registry.at('Foo').should be_nil
+      checks.should == [:one]
+    end
+    
+    it "should not cancel on nil" do
+      checks = []
+      before_list { checks << :one }
+      before_list { nil }
+      before_list { checks << :two }
+      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
+      Registry.at('Foo').should_not be_nil
+      checks.should == [:one, :two]
+    end
+    
+    it "should pass in globals" do
+      before_list {|f,g| g.x = 1 }
+      before_list {|f,g| g.x += 1 }
+      before_list {|f,g| g.x += 1 }
+      after_list {|f,g| g.x.should == 3 }
+      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
+      Registry.at('Foo').should_not be_nil
+    end
+  end
+
+  describe '.after_parse_list' do
+    before do
+      Parser::SourceParser.before_parse_list_callbacks.clear
+      Parser::SourceParser.after_parse_list_callbacks.clear
+    end
+
+    it "should handle basic callback support and maintain files/globals" do
+      before_list do |f,g| g.foo = :bar end
+      after_list do |files, globals|
+        files.should == ['foo.rb', 'bar.rb']
+        globals.foo.should == :bar
+      end
+      parse_list ['foo.rb', 'foo!'], ['bar.rb', 'class Foo; end']
+      Registry.at('Foo').should_not be_nil
+    end
+    
+    it "should support multiple callbacks" do
+      checks = []
+      after_list { checks << :one }
+      after_list { checks << :two }
+      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
+      Registry.at('Foo').should_not be_nil  
+      checks.should == [:one, :two]
+    end
+    
+    it "should not cancel parsing if it returns false" do
+      checks = []
+      after_list { checks << :one }
+      after_list { false }
+      after_list { checks << :three }
+      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
+      Registry.at('Foo').should_not be_nil
+      checks.should == [:one, :three]
+    end
+  end
+
+  describe '.before_parse_file' do
+    before do
+      Parser::SourceParser.before_parse_file_callbacks.clear
+      Parser::SourceParser.after_parse_file_callbacks.clear
+    end
+
+    it "should handle basic callback support" do
+      before_file do |parser|
+        parser.contents.should == 'class Foo; end'
+        parser.file.should =~ /(foo|bar)\.rb/
+      end
+      parse_list ['foo.rb', 'class Foo; end'], ['bar.rb', 'class Foo; end']
+      Registry.at('Foo').should_not be_nil
+    end
+    
+    it "should support multiple callbacks" do
+      checks = []
+      before_file { checks << :one }
+      before_file { checks << :two }
+      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
+      Registry.at('Foo').should_not be_nil  
+      checks.should == [:one, :two, :one, :two, :one, :two]
+    end
+    
+    it "should cancel parsing if it returns false" do
+      checks = []
+      before_file { checks << :one }
+      before_file { false }
+      before_file { checks << :three }
+      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
+      Registry.at('Foo').should be_nil
+      checks.should == [:one, :one, :one]
+    end
+    
+    it "should not cancel on nil" do
+      checks = []
+      before_file { checks << :one }
+      before_file { nil }
+      before_file { checks << :two }
+      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
+      Registry.at('Foo').should_not be_nil
+      checks.should == [:one, :two, :one, :two, :one, :two]
+    end
+  end
+  
+  describe '.after_parse_file' do
+    before do
+      Parser::SourceParser.before_parse_file_callbacks.clear
+      Parser::SourceParser.after_parse_file_callbacks.clear
+    end
+
+    it "should handle basic callback support" do
+      after_file do |parser|
+        parser.contents.should == 'class Foo; end'
+        parser.file.should =~ /(foo|bar)\.rb/
+      end
+      parse_list ['foo.rb', 'class Foo; end'], ['bar.rb', 'class Foo; end']
+      Registry.at('Foo').should_not be_nil
+    end
+    
+    it "should support multiple callbacks" do
+      checks = []
+      after_file { checks << :one }
+      after_file { checks << :two }
+      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
+      Registry.at('Foo').should_not be_nil  
+      checks.should == [:one, :two, :one, :two, :one, :two]
+    end
+    
+    it "should not cancel parsing if it returns false" do
+      checks = []
+      after_file { checks << :one }
+      after_file { false }
+      after_file { checks << :three }
+      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
+      Registry.at('Foo').should_not be_nil
+      checks.should == [:one, :three, :one, :three, :one, :three]
+    end
+  end
+  
   describe '.register_parser_type' do
     it_should_behave_like "parser type registration"
     
@@ -141,6 +336,17 @@ describe YARD::Parser::SourceParser do
       Registry.at(:Hello).docstring.should == "PASS"
     end
     
+    it "should strip all hashes prefixed on comment line" do
+      YARD.parse_string(<<-eof)
+        ### PASS
+        #### PASS
+        ##### PASS
+        module Hello
+        end
+      eof
+      Registry.at(:Hello).docstring.should == "PASS\nPASS\nPASS"
+    end
+    
     it "should handle =begin/=end style comments" do
       YARD.parse_string "=begin\nfoo\nbar\n=end\nclass Foo; end\n"
       Registry.at(:Foo).docstring.should == "foo\nbar"
@@ -168,6 +374,23 @@ describe YARD::Parser::SourceParser do
       YARD.parse_string "# encoding: utf-8\n# this is a comment\nclass Foo; end"
       Registry.at(:Foo).docstring.should == "this is a comment"
     end
+    
+    it "should add macros on any object" do
+      YARD.parse_string <<-eof
+        # @macro [new] foo
+        # This is a macro
+        # @return [String] the string
+        class Foo
+          # @macro foo
+          def foo; end
+        end
+      eof
+      
+      macro = CodeObjects::MacroObject.find('foo')
+      macro.macro_data.should == "This is a macro\n@return [String] the string"
+      Registry.at('Foo').docstring.all.should ==  macro.macro_data
+      Registry.at('Foo#foo').docstring.all.should == macro.macro_data
+    end
   end
 
   describe '#parse' do
@@ -270,6 +493,18 @@ describe YARD::Parser::SourceParser do
         end
       end
     end
+
+    Parser::SourceParser::ENCODING_BYTE_ORDER_MARKS.each do |encoding, bom|
+      it "should understand #{encoding.upcase} BOM" do
+        parser = Parser::SourceParser.new
+        src = bom + "class FooBar; end".force_encoding('binary')
+        src.force_encoding('binary')
+        File.should_receive(:read_binary).with('tmpfile').and_return(src)
+        result = parser.parse('tmpfile')
+        Registry.all(:class).first.path.should == "FooBar"
+        result.enumerator[0].source.encoding.to_s.downcase.should == encoding
+      end
+    end if HAVE_RIPPER && RUBY19
   end
   
   describe '#parse_in_order' do