yard 0.7.5 → 0.8.0

data/spec/parser/source_parser_spec.rb

@@ -10,10 +10,10 @@ shared_examples_for "parser type registration" do
 end
 
 describe YARD::Parser::SourceParser do
-  before do 
+  before do
     Registry.clear
   end
-  
+
   def parse_list(*list)
     files = list.map do |v|
       filename, source = *v
@@ -38,7 +38,7 @@ describe YARD::Parser::SourceParser do
   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
@@ -53,16 +53,16 @@ describe YARD::Parser::SourceParser do
       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  
+      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 }
@@ -72,7 +72,7 @@ describe YARD::Parser::SourceParser do
       Registry.at('Foo').should be_nil
       checks.should == [:one]
     end
-    
+
     it "should not cancel on nil" do
       checks = []
       before_list { checks << :one }
@@ -82,7 +82,7 @@ describe YARD::Parser::SourceParser do
       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 }
@@ -108,16 +108,16 @@ describe YARD::Parser::SourceParser do
       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  
+      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 }
@@ -143,16 +143,16 @@ describe YARD::Parser::SourceParser do
       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  
+      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 }
@@ -162,7 +162,7 @@ describe YARD::Parser::SourceParser do
       Registry.at('Foo').should be_nil
       checks.should == [:one, :one, :one]
     end
-    
+
     it "should not cancel on nil" do
       checks = []
       before_file { checks << :one }
@@ -173,7 +173,7 @@ describe YARD::Parser::SourceParser do
       checks.should == [:one, :two, :one, :two, :one, :two]
     end
   end
-  
+
   describe '.after_parse_file' do
     before do
       Parser::SourceParser.before_parse_file_callbacks.clear
@@ -188,16 +188,16 @@ describe YARD::Parser::SourceParser do
       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  
+      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 }
@@ -208,10 +208,10 @@ describe YARD::Parser::SourceParser do
       checks.should == [:one, :three, :one, :three, :one, :three]
     end
   end
-  
+
   describe '.register_parser_type' do
     it_should_behave_like "parser type registration"
-    
+
     it "should register a subclass of Parser::Base" do
       parser = mock(:parser)
       parser.should_receive(:parse)
@@ -219,14 +219,14 @@ describe YARD::Parser::SourceParser do
       Parser::SourceParser.register_parser_type(:my_parser, MyParser, 'myparser')
       Parser::SourceParser.parse_string('content', :my_parser)
     end
-    
+
     it "should require class to be a subclass of Parser::Base" do
       lambda { Parser::SourceParser.register_parser_type(:my_parser, String) }.should raise_error(ArgumentError)
       lambda { Parser::SourceParser.register_parser_type(:my_parser, Parser::Base) }.should raise_error(ArgumentError)
     end
   end
-  
-  describe '.parser_type_for_extension' do 
+
+  describe '.parser_type_for_extension' do
     it_should_behave_like "parser type registration"
 
     it "should find an extension in a registered array of extensions" do
@@ -236,26 +236,26 @@ describe YARD::Parser::SourceParser do
       Parser::SourceParser.parser_type_for_extension('d').should == :my_parser
       Parser::SourceParser.parser_type_for_extension('c').should_not == :my_parser
     end
-    
+
     it "should find an extension in a Regexp" do
       Parser::SourceParser.register_parser_type(:my_parser, MyParser, /abc$/)
       Parser::SourceParser.parser_type_for_extension('dabc').should == :my_parser
       Parser::SourceParser.parser_type_for_extension('dabcd').should_not == :my_parser
     end
-    
+
     it "should find an extension in a list of Regexps" do
       Parser::SourceParser.register_parser_type(:my_parser, MyParser, [/ab$/, /abc$/])
       Parser::SourceParser.parser_type_for_extension('dabc').should == :my_parser
       Parser::SourceParser.parser_type_for_extension('dabcd').should_not == :my_parser
     end
-    
+
     it "should find an extension in a String" do
       Parser::SourceParser.register_parser_type(:my_parser, MyParser, "abc")
       Parser::SourceParser.parser_type_for_extension('abc').should == :my_parser
       Parser::SourceParser.parser_type_for_extension('abcd').should_not == :my_parser
     end
   end
-  
+
   describe '#parse_string' do
     it "should parse basic Ruby code" do
       YARD.parse_string(<<-eof)
@@ -272,7 +272,7 @@ describe YARD::Parser::SourceParser do
       Registry.at("Hello::Hi#me").docstring.should == "Docstring\nDocstring2"
       Registry.at("Hello::Hi#me").docstring.line_range.should == (3..4)
     end
-    
+
     it "should parse Ruby code with metaclasses" do
       YARD.parse_string(<<-eof)
         module Hello
@@ -288,18 +288,18 @@ describe YARD::Parser::SourceParser do
       Registry.at("Hello::Hi.me").should_not == nil
       Registry.at("Hello::Hi.me").docstring.should == "Docstring"
     end
-    
+
     it "should only use prepended comments for an object" do
       YARD.parse_string(<<-eof)
         # Test
-        
+
         # PASS
         module Hello
         end # FAIL
       eof
       Registry.at(:Hello).docstring.should == "PASS"
     end
-    
+
     it "should not add comments appended to last line of block" do
       YARD.parse_string <<-eof
         module Hello2
@@ -307,7 +307,7 @@ describe YARD::Parser::SourceParser do
       eof
       Registry.at(:Hello2).docstring.should be_blank
     end
-    
+
     it "should add comments appended to an object's first line" do
       YARD.parse_string <<-eof
         module Hello # PASS
@@ -324,7 +324,7 @@ describe YARD::Parser::SourceParser do
       Registry.at(:Hello2).docstring.should == "PASS"
       Registry.at('Hello2#x').docstring.should == "ANOTHER PASS"
     end
-    
+
     it "should take preceeding comments only if they exist" do
       YARD.parse_string <<-eof
         # PASS
@@ -335,7 +335,7 @@ 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
@@ -346,7 +346,7 @@ describe YARD::Parser::SourceParser do
       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"
@@ -357,39 +357,97 @@ describe YARD::Parser::SourceParser do
       YARD.parse_string "=begin\nfoo\n\nbar\n=end\nclass Foo; end\n"
       Registry.at(:Foo).docstring.should == "foo\n\nbar"
     end
-    
+
     it "should know about docstrings starting with ##" do
       {'#' => false, '##' => true}.each do |hash, expected|
         YARD.parse_string "#{hash}\n# Foo bar\nclass Foo; end"
         Registry.at(:Foo).docstring.hash_flag.should == expected
       end
     end
-    
+
     it "should remove shebang from initial file comments" do
       YARD.parse_string "#!/bin/ruby\n# this is a comment\nclass Foo; end"
       Registry.at(:Foo).docstring.should == "this is a comment"
     end
-    
+
     it "should remove encoding line from initial file comments" 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
+        # @!macro [new] foo
+        #   This is a macro
+        #   @return [String] the string
         class Foo
-          # @macro 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
+      Registry.at('Foo').docstring.to_raw.should ==  macro.macro_data
+      Registry.at('Foo#foo').docstring.to_raw.should == macro.macro_data
+    end
+
+    it "should allow directives parsed on lone comments" do
+      YARD.parse_string(<<-eof)
+        class Foo
+          # @!method foo(a = "hello")
+          # @!scope class
+          # @!visibility private
+          # @param [String] a the name of the foo
+          # @return [Symbol] the symbolized foo
+
+          # @!method bar(value)
+        end
+      eof
+      foo = Registry.at('Foo.foo')
+      bar = Registry.at('Foo#bar')
+      foo.should_not be_nil
+      foo.visibility.should == :private
+      foo.tag(:param).name.should == 'a'
+      foo.tag(:return).types.should == ['Symbol']
+      bar.should_not be_nil
+      bar.signature.should == 'def bar(value)'
+    end
+
+    it "should parse lone comments at end of blocks" do
+      YARD.parse_string(<<-eof)
+        class Foo
+          none
+
+          # @!method foo(a = "hello")
+        end
+      eof
+      foo = Registry.at('Foo#foo')
+      foo.should_not be_nil
+      foo.signature.should == 'def foo(a = "hello")'
+    end
+
+    it "should handle lone comment with no code" do
+      YARD.parse_string '# @!method foo(a = "hello")'
+      foo = Registry.at('#foo')
+      foo.should_not be_nil
+      foo.signature.should == 'def foo(a = "hello")'
+    end
+
+    it "should handle non-ASCII encoding in heredoc" do
+      YARD.parse_string <<-eof
+        # encoding: utf-8
+
+        heredoc <<-ending
+          foo\u{ffe2} bar.
+        ending
+
+        # Hello \u{ffe2} world
+        class Foo < Bar
+          attr_accessor :foo
+        end
+      eof
+      Registry.at('Foo').superclass.should == P('Bar')
     end
   end
 
@@ -400,19 +458,19 @@ describe YARD::Parser::SourceParser do
       Registry.at("Hello::Hi#me").should_not == nil
       Registry.at("Hello::Hi#me").docstring.should == "Docstring"
     end
-  
+
     it "should parse a set of file globs" do
       Dir.should_receive(:[]).with('lib/**/*.rb').and_return([])
       YARD.parse('lib/**/*.rb')
     end
-  
+
     it "should parse a set of absolute paths" do
       Dir.should_not_receive(:[]).and_return([])
       File.should_receive(:file?).with('/path/to/file').and_return(true)
       File.should_receive(:read_binary).with('/path/to/file').and_return("")
       YARD.parse('/path/to/file')
     end
-    
+
     it "should clean paths before parsing" do
       File.should_receive(:open).and_return("")
       parser = Parser::SourceParser.new(:ruby, true)
@@ -430,7 +488,7 @@ describe YARD::Parser::SourceParser do
       File.should_receive(:read_binary).with('b.rb').and_return("")
       YARD.parse ['/path/to/file', '*.rb']
     end
-    
+
     it "should convert directories into globs" do
       Dir.should_receive(:[]).with('foo/**/*.{rb,c}').and_return(['foo/a.rb', 'foo/bar/b.rb'])
       File.should_receive(:directory?).with('foo').and_return(true)
@@ -440,7 +498,7 @@ describe YARD::Parser::SourceParser do
       File.should_receive(:read_binary).with('foo/bar/b.rb').and_return("")
       YARD.parse ['foo']
     end
-    
+
     it "should use Registry.checksums cache if file is cached" do
       data = 'DATA'
       hash = Registry.checksum_for(data)
@@ -451,14 +509,14 @@ describe YARD::Parser::SourceParser do
       File.should_receive(:read_binary).with('foo/bar').and_return(data)
       YARD.parse('foo/bar')
     end
-    
+
     it "should support excluded paths" do
       File.should_receive(:file?).with('foo/bar').and_return(true)
       File.should_receive(:file?).with('foo/baz').and_return(true)
       File.should_not_receive(:read_binary)
       YARD.parse(["foo/bar", "foo/baz"], ["foo", /baz$/])
     end
-    
+
     it "should convert file contents to proper encoding if coding line is present" do
       valid = []
       valid << "# encoding: sjis"
@@ -528,13 +586,13 @@ describe YARD::Parser::SourceParser do
       end
     end if HAVE_RIPPER && RUBY19
   end
-  
+
   describe '#parse_in_order' do
     def in_order_parse(*files)
       paths = files.map {|f| File.join(File.dirname(__FILE__), 'examples', f.to_s + '.rb.txt') }
       YARD::Parser::SourceParser.parse(paths, [], Logger::DEBUG)
     end
-    
+
     it "should attempt to parse files in order" do
       msgs = []
       log.should_receive(:debug) {|m| msgs << m }.at_least(:once)
@@ -543,8 +601,8 @@ describe YARD::Parser::SourceParser do
       msgs[2].should =~ /Missing object MyModule/
       msgs[3].should =~ /Processing .+parse_in_order_002.+/
       msgs[4].should =~ /Re-processing .+parse_in_order_001.+/
-    end if CONTINUATIONS_SUPPORTED
-    
+    end
+
     it "should attempt to order files by length (process toplevel files first)" do
       %w(a a/b a/b/c).each do |file|
         File.should_receive(:file?).with(file).and_return(true)
@@ -553,21 +611,23 @@ describe YARD::Parser::SourceParser do
       YARD.parse %w(a/b/c a/b a)
     end
   end
-  
+
   describe '#parse_statements' do
     it "should display a warning for invalid parser type" do
       log.should_receive(:warn).with(/unrecognized file/)
+      log.should_receive(:backtrace)
       YARD::Parser::SourceParser.parse_string("int main() { }", :d)
     end
-    
+
     if HAVE_RIPPER
       it "should display a warning for a syntax error (with new parser)" do
         err_msg = "Syntax error in `(stdin)`:(1,3): syntax error, unexpected $undefined, expecting $end"
         log.should_receive(:warn).with(err_msg)
+        log.should_receive(:backtrace)
         YARD::Parser::SourceParser.parse_string("$$$", :ruby)
       end
     end
-    
+
     it "should handle groups" do
       Registry.clear
       YARD.parse_string <<-eof
@@ -575,16 +635,16 @@ describe YARD::Parser::SourceParser do
           # @group Group Name
           def foo; end
           def foo2; end
-        
+
           # @endgroup
-        
+
           def bar; end
-          
+
           # @group Group 2
           def baz; end
         end
       eof
-      
+
       Registry.at('A').groups.should == ['Group Name', 'Group 2']
       Registry.at('A#bar').group.should be_nil
       Registry.at('A#foo').group.should == "Group Name"