yard 0.7.5 → 0.8.0

data/spec/config_spec.rb

@@ -5,7 +5,7 @@ require 'yaml'
 describe YARD::Config do
   describe '.load' do
     before do
-      File.should_receive(:file?).with(CLI::Yardoc::DEFAULT_YARDOPTS_FILE).and_return(false)
+      File.should_receive(:file?).twice.with(CLI::Yardoc::DEFAULT_YARDOPTS_FILE).and_return(false)
     end
 
     it "should use default options if no ~/.yard/config is found" do
@@ -14,7 +14,7 @@ describe YARD::Config do
       YARD::Config.load
       YARD::Config.options.should == YARD::Config::DEFAULT_CONFIG_OPTIONS
     end
-    
+
     it "should overwrite options with data in ~/.yard/config" do
       File.should_receive(:file?).with(YARD::Config::CONFIG_FILE).and_return(true)
       File.should_receive(:file?).with(YARD::Config::IGNORED_PLUGINS).and_return(false)
@@ -22,7 +22,7 @@ describe YARD::Config do
       YARD::Config.load
       YARD::Config.options[:test].should be_true
     end
-    
+
     it "should ignore any plugins specified in '~/.yard/ignored_plugins'" do
       File.should_receive(:file?).with(YARD::Config::CONFIG_FILE).and_return(false)
       File.should_receive(:file?).with(YARD::Config::IGNORED_PLUGINS).and_return(true)
@@ -32,8 +32,17 @@ describe YARD::Config do
       YARD::Config.should_not_receive(:require).with('yard-plugin2')
       YARD::Config.load_plugin('yard-plugin2').should == false
     end
+
+    it "should load safe_mode setting from --safe command line option" do
+      File.should_receive(:file?).with(YARD::Config::IGNORED_PLUGINS).and_return(false)
+      File.should_receive(:file?).with(YARD::Config::CONFIG_FILE).and_return(false)
+      ARGV.replace(['--safe'])
+      YARD::Config.load
+      YARD::Config.options[:safe_mode].should be_true
+      ARGV.replace([''])
+    end
   end
-  
+
   describe '.save' do
     it "should save options to config file" do
       YARD::Config.stub!(:options).and_return(:a => 1, :b => %w(a b c))
@@ -43,51 +52,51 @@ describe YARD::Config do
       YARD::Config.save
     end
   end
-  
+
   describe '.load_plugin' do
     it "should load a plugin by 'name' as 'yard-name'" do
       YARD::Config.should_receive(:require).with('yard-foo')
       log.should_receive(:debug).with(/Loading plugin 'yard-foo'/).once
       YARD::Config.load_plugin('foo').should == true
     end
-    
+
     it "should not load plugins like 'doc-*'" do
       YARD::Config.should_not_receive(:require).with('yard-doc-core')
       YARD::Config.load_plugin('doc-core')
       YARD::Config.load_plugin('yard-doc-core')
     end
-    
+
     it "should load plugin by 'yard-name' as 'yard-name'" do
       YARD::Config.should_receive(:require).with('yard-foo')
       log.should_receive(:debug).with(/Loading plugin 'yard-foo'/).once
       YARD::Config.load_plugin('yard-foo').should == true
     end
-    
+
     it "should load plugin by 'yard_name' as 'yard_name'" do
       YARD::Config.should_receive(:require).with('yard_foo')
       log.should_receive(:debug).with(/Loading plugin 'yard_foo'/).once
       log.show_backtraces = false
       YARD::Config.load_plugin('yard_foo').should == true
     end
-    
+
     it "should log error if plugin is not found" do
       YARD::Config.should_receive(:require).with('yard-foo').and_raise(LoadError)
       log.should_receive(:warn).with(/Error loading plugin 'yard-foo'/).once
       YARD::Config.load_plugin('yard-foo').should == false
     end
-    
+
     it "should sanitize plugin name (remove /'s)" do
       YARD::Config.should_receive(:require).with('yard-foofoo')
       YARD::Config.load_plugin('foo/foo').should == true
     end
-    
+
     it "should ignore plugins in :ignore_plugins" do
       YARD::Config.stub!(:options).and_return(:ignored_plugins => ['yard-foo', 'yard-bar'])
       YARD::Config.load_plugin('foo').should == false
       YARD::Config.load_plugin('bar').should == false
     end
   end
-  
+
   describe '.load_plugins' do
     it "should load gem plugins if :load_plugins is true" do
       YARD::Config.stub!(:options).and_return(:load_plugins => true, :ignored_plugins => [], :autoload_plugins => [])
@@ -95,42 +104,42 @@ describe YARD::Config do
       YARD::Config.should_receive(:require).with('rubygems')
       YARD::Config.load_plugins
     end
-    
+
     it "should ignore gem loading if RubyGems cannot load" do
       YARD::Config.stub!(:options).and_return(:load_plugins => true, :ignored_plugins => [], :autoload_plugins => [])
       YARD::Config.should_receive(:require).with('rubygems').and_raise(LoadError)
       YARD::Config.load_plugins.should == false
     end
-    
+
     it "should load certain plugins automatically when specified in :autoload_plugins" do
       File.should_receive(:file?).with(CLI::Yardoc::DEFAULT_YARDOPTS_FILE).and_return(false)
       YARD::Config.stub!(:options).and_return(:load_plugins => false, :ignored_plugins => [], :autoload_plugins => ['yard-plugin'])
       YARD::Config.should_receive(:require).with('yard-plugin').and_return(true)
       YARD::Config.load_plugins.should == true
     end
-    
+
     it "should parse --plugin from command line arguments" do
       YARD::Config.should_receive(:arguments).at_least(1).times.and_return(%w(--plugin foo --plugin bar a b c))
       YARD::Config.should_receive(:load_plugin).with('foo').and_return(true)
       YARD::Config.should_receive(:load_plugin).with('bar').and_return(true)
       YARD::Config.load_plugins.should == true
     end
-    
+
     it "should load --plugin arguments from .yardopts" do
-      File.should_receive(:file?).with(CLI::Yardoc::DEFAULT_YARDOPTS_FILE).once.and_return(true)
+      File.should_receive(:file?).with(CLI::Yardoc::DEFAULT_YARDOPTS_FILE).twice.and_return(true)
       File.should_receive(:file?).with(YARD::Config::CONFIG_FILE).and_return(false)
       File.should_receive(:file?).with(YARD::Config::IGNORED_PLUGINS).and_return(false)
-      File.should_receive(:read_binary).with(CLI::Yardoc::DEFAULT_YARDOPTS_FILE).once.and_return('--plugin foo')
+      File.should_receive(:read_binary).with(CLI::Yardoc::DEFAULT_YARDOPTS_FILE).twice.and_return('--plugin foo')
       YARD::Config.should_receive(:load_plugin).with('foo')
       YARD::Config.load
     end
-    
+
     it "should load any gem plugins starting with 'yard_' or 'yard-'" do
       File.should_receive(:file?).with(CLI::Yardoc::DEFAULT_YARDOPTS_FILE).and_return(false)
       YARD::Config.stub!(:options).and_return(:load_plugins => true, :ignored_plugins => ['yard_plugin'], :autoload_plugins => [])
       plugins = {
-        'yard' => mock('yard'), 
-        'yard_plugin' => mock('yard_plugin'), 
+        'yard' => mock('yard'),
+        'yard_plugin' => mock('yard_plugin'),
         'yard-plugin' => mock('yard-plugin'),
         'my-yard-plugin' => mock('yard-plugin'),
         'rspec' => mock('rspec'),
@@ -138,7 +147,7 @@ describe YARD::Config do
       plugins.each do |k, v|
         v.should_receive(:name).at_least(1).times.and_return(k)
       end
-      
+
       source_mock = mock(:source_index)
       source_mock.should_receive(:find_name).with('').and_return(plugins.values)
       Gem.should_receive(:source_index).and_return(source_mock)
@@ -146,7 +155,7 @@ describe YARD::Config do
       YARD::Config.should_receive(:load_plugin).with('yard-plugin').and_return(true)
       YARD::Config.load_plugins.should == true
     end
-    
+
     it "should log an error if a gem raises an error" do
       YARD::Config.stub!(:options).and_return(:load_plugins => true, :ignored_plugins => [], :autoload_plugins => [])
       plugins = {
@@ -155,7 +164,7 @@ describe YARD::Config do
       plugins.each do |k, v|
         v.should_receive(:name).at_least(1).times.and_return(k)
       end
-      
+
       source_mock = mock(:source_index)
       source_mock.should_receive(:find_name).with('').and_return(plugins.values)
       Gem.should_receive(:source_index).and_return(source_mock)

data/spec/core_ext/array_spec.rb

@@ -5,7 +5,7 @@ describe Array do
     it "should create an Insertion object" do
       [].place('x').should be_kind_of(Insertion)
     end
-    
+
     it "should allow multiple objects to be placed" do
       [1, 2].place('x', 'y', 'z').before(2).should == [1, 'x', 'y', 'z', 2]
     end

data/spec/core_ext/file_spec.rb

@@ -5,26 +5,26 @@ describe File do
     it "should return the relative path between two files" do
       File.relative_path('a/b/c/d.html', 'a/b/d/q.html').should == '../d/q.html'
     end
-  
+
     it "should return the relative path between two directories" do
       File.relative_path('a/b/c/d/', 'a/b/d/').should == '../d'
     end
-  
+
     it "should return only the to file if from file is in the same directory as the to file" do
       File.relative_path('a/b/c/d', 'a/b/c/e').should == 'e'
     end
-  
+
     it "should handle non-normalized paths" do
       File.relative_path('Hello/./I/Am/Fred', 'Hello/Fred').should == '../../Fred'
       File.relative_path('A//B/C', 'Q/X').should == '../../Q/X'
     end
   end
-  
+
   describe '.cleanpath' do
     it "should clean double brackets" do
       File.cleanpath('A//B/C').should == "A/B/C"
     end
-    
+
     it "should clean a path with ." do
       File.cleanpath('Hello/./I/.Am/Fred').should == "Hello/I/.Am/Fred"
     end
@@ -40,16 +40,16 @@ describe File do
     it "should clean a path ending in .." do
       File.cleanpath('A/B/C/D/..').should == "A/B/C"
     end
-    
+
     it "should pass the initial directory" do
       File.cleanpath('C/../../D').should == "../D"
     end
-    
+
     it "should not remove multiple '../' at the beginning" do
       File.cleanpath('../../A/B').should == '../../A/B'
     end
   end
-  
+
   describe '.open!' do
     it "should create the path before opening" do
       File.should_receive(:directory?).with('/path/to').and_return(false)

data/spec/core_ext/hash_spec.rb

@@ -6,7 +6,7 @@ describe Hash do
       list = [['foo', 'bar'], ['foo2', 'bar2']]
       Hash[list].should == {'foo' => 'bar', 'foo2' => 'bar2'}
     end
-    
+
     it "should accept an array as a key" do
       Hash[['a', 'b'], 1].should == {['a', 'b'] => 1}
     end

data/spec/core_ext/insertion_spec.rb

@@ -8,7 +8,7 @@ describe Insertion do
       [1, [4], 2].place(3).before(2).should == [1, [4], 3, 2]
     end
   end
-  
+
   describe '#after' do
     it "should place an object after another" do
       [1, 2].place(3).after(2).should == [1, 2, 3]
@@ -17,12 +17,12 @@ describe Insertion do
     it "should no longer place an object after another and its subsections (0.6)" do
       [1, [2]].place(3).after(1).should == [1, 3, [2]]
     end
-    
+
     it "should place an array after an object" do
       [1, 2, 3].place([4]).after(1).should == [1, [4], 2, 3]
     end
   end
-  
+
   describe '#before_any' do
     it "should place an object before another anywhere inside list (including sublists)" do
       [1, 2, [3]].place(4).before_any(3).should == [1, 2, [4, 3]]

data/spec/core_ext/module_spec.rb

@@ -6,7 +6,7 @@ describe Module do
       YARD::CodeObjects::Base.class_name.should == "Base"
     end
   end
-  
+
   describe '#namespace' do
     it "should return everything before the class name" do
       YARD::CodeObjects::Base.namespace_name.should == "YARD::CodeObjects"

data/spec/core_ext/string_spec.rb

@@ -8,27 +8,27 @@ describe String do
     it "should split simple non-quoted text" do
       "a b c".shell_split.should == %w(a b c)
     end
-    
+
     it "should split double quoted text into single token" do
       'a "b c d" e'.shell_split.should == ["a", "b c d", "e"]
     end
-    
+
     it "should split single quoted text into single token" do
       "a 'b c d' e".shell_split.should == ["a", "b c d", "e"]
     end
-    
+
     it "should handle escaped quotations in quotes" do
       "'a \\' b'".shell_split.should == ["a ' b"]
     end
-    
+
     it "should handle escaped quotations outside quotes" do
       "\\'a 'b'".shell_split.should == %w('a b)
     end
-    
+
     it "should handle escaped backslash" do
       "\\\\'a b c'".shell_split.should == ['\a b c']
     end
-    
+
     it "should handle any whitespace as space" do
       text = "foo\tbar\nbaz\r\nfoo2 bar2"
       text.shell_split.should == %w(foo bar baz foo2 bar2)

data/spec/core_ext/symbol_hash_spec.rb

@@ -1,14 +1,14 @@
 require File.join(File.dirname(__FILE__), '..', 'spec_helper')
 
 describe SymbolHash do
-  
+
   it "should allow access to keys as String or Symbol" do
     h = SymbolHash.new(false)
     h['test'] = true
     h[:test].should == true
     h['test'].should == true
   end
-    
+
   it "should #delete by key as String or Symbol" do
     h = SymbolHash.new
     h.keys.length.should == 0
@@ -25,36 +25,36 @@ describe SymbolHash do
     h.delete('test')
     h.keys.length.should == 0
   end
-  
+
   it "should return same #has_key? for key as String or Symbol" do
     h = SymbolHash.new
     h[:test] = 1
     h.has_key?(:test).should == true
     h.has_key?('test').should == true
   end
-  
+
   it "should symbolize value if it is a String (and only a string)" do
     class Substring < String; end
-      
+
     h = SymbolHash.new
     h['test1'] = "hello"
     h['test2'] = Substring.new("hello")
     h['test1'].should == :hello
     h['test2'].should == "hello"
-  end 
-  
+  end
+
   it "should not symbolize value if SymbolHash.new(false) is created" do
     h = SymbolHash.new(false)
     h['test'] = "hello"
     h[:test].should == "hello"
   end
-  
+
   it "should not symbolize value if it is not a String" do
     h = SymbolHash.new
     h['test'] = [1,2,3]
     h['test'].should == [1,2,3]
   end
-  
+
   it "should support symbolization using #update or #merge!" do
     h = SymbolHash.new
     h.update('test' => 'value')
@@ -68,13 +68,13 @@ describe SymbolHash do
     h.merge('test' => 'value')[:test].should == :value
     h.should == SymbolHash.new
   end
-  
+
   it "should support #initializing of a hash" do
     h = SymbolHash[:test => 1]
     h[:test].should == 1
     h[:somethingelse].should be_nil
   end
-  
+
   it "should support reverse merge syntax" do
     opts = {}
     opts = SymbolHash[

data/spec/docstring_parser_spec.rb

@@ -0,0 +1,207 @@
+require File.dirname(__FILE__) + "/spec_helper"
+
+describe YARD::DocstringParser do
+  def parse(content, object = nil, handler = nil)
+    @library ||= Tags::Library.instance
+    @parser = DocstringParser.new(@library)
+    @parser.parse(content, object, handler)
+    @parser
+  end
+
+  def docstring(content, object = nil, handler = nil)
+    parse(content, object, handler).to_docstring
+  end
+
+  describe '#parse' do
+    it "should parse comments into tags" do
+      doc = docstring(<<-eof)
+@param name Hello world
+  how are you?
+@param name2
+  this is a new line
+@param name3 and this
+  is a new paragraph:
+
+  right here.
+      eof
+      tags = doc.tags(:param)
+      tags[0].name.should == "name"
+      tags[0].text.should == "Hello world\nhow are you?"
+      tags[1].name.should == "name2"
+      tags[1].text.should == "this is a new line"
+      tags[2].name.should == "name3"
+      tags[2].text.should == "and this\nis a new paragraph:\n\nright here."
+    end
+
+    it "should end parsing a tag on de-dent" do
+      doc = docstring(<<-eof)
+@note test
+  one two three
+rest of docstring
+      eof
+      doc.tag(:note).text.should == "test\none two three"
+      doc.should == "rest of docstring"
+    end
+
+    it "should parse examples embedded in doc" do
+      doc = docstring(<<-eof)
+test string here
+@example code
+
+  def foo(x, y, z)
+  end
+
+  class A; end
+
+more stuff
+eof
+      doc.should == "test string here\nmore stuff"
+      doc.tag(:example).text.should == "\ndef foo(x, y, z)\nend\n\nclass A; end"
+    end
+
+    it "should remove only original indentation from beginning of line in tags" do
+      doc = docstring(<<-eof)
+@param name
+  some value
+  foo bar
+   baz
+eof
+      doc.tag(:param).text.should == "some value\nfoo bar\n baz"
+    end
+
+    it "should allow numbers in tags" do
+      Tags::Library.define_tag(nil, :foo1)
+      Tags::Library.define_tag(nil, :foo2)
+      Tags::Library.define_tag(nil, :foo3)
+      doc = docstring(<<-eof)
+@foo1 bar1
+@foo2 bar2
+@foo3 bar3
+eof
+      doc.tag(:foo1).text.should == "bar1"
+      doc.tag(:foo2).text.should == "bar2"
+    end
+
+    it "should end tag on newline if next line is not indented" do
+      doc = docstring(<<-eof)
+@author bar1
+@api bar2
+Hello world
+eof
+      doc.tag(:author).text.should == "bar1"
+      doc.tag(:api).text.should == "bar2"
+    end
+
+    it "should warn about unknown tag" do
+      log.should_receive(:warn).with(/Unknown tag @hello$/)
+      docstring("@hello world")
+    end
+
+    it "should not add trailing whitespace to freeform tags" do
+      doc = docstring("@api private   \t   ")
+      doc.tag(:api).text.should == "private"
+    end
+  end
+
+  describe '#parse with custom tag library' do
+    class TestLibrary < Tags::Library; end
+
+    before { @library = TestLibrary.new }
+
+    it "should accept valid tags" do
+      valid = %w( testing valid is_a is_A __ )
+      valid.each do |tag|
+        TestLibrary.define_tag("Tag", tag)
+        doc = docstring('@' + tag + ' foo bar')
+        doc.tag(tag).text.should == 'foo bar'
+      end
+    end
+
+    it "should not parse invalid tag names" do
+      invalid = %w( @ @return@ @param, @x-y @.x.y.z )
+      invalid.each do |tag|
+        docstring(tag + ' foo bar').should == tag + ' foo bar'
+      end
+    end
+
+    it "should allow namespaced tags in the form @x.y.z" do
+      TestLibrary.define_tag("Tag", 'x.y.z')
+      doc = docstring("@x.y.z foo bar")
+      doc.tag('x.y.z').text.should == 'foo bar'
+    end
+
+    it "should ignore new directives without @! prefix syntax" do
+      TestLibrary.define_directive('dir1', Tags::ScopeDirective)
+      log.should_receive(:warn).with(/@dir1/)
+      docstring("@dir1")
+    end
+
+    %w(attribute endgroup group macro method scope visibility).each do |tag|
+      it "should handle non prefixed @#{tag} syntax as directive, not tag" do
+        TestLibrary.define_directive(tag, Tags::ScopeDirective)
+        parse("@#{tag}")
+        @parser.directives.first.should be_a(Tags::ScopeDirective)
+      end
+    end
+
+    it "should handle directives with @! prefix syntax" do
+      TestLibrary.define_directive('dir1', Tags::ScopeDirective)
+      docstring("@!dir1 class")
+      @parser.state.scope.should == :class
+    end
+  end
+
+  describe '#text' do
+    it "should only return text data" do
+      parse("Foo\n@param foo x y z\nBar")
+      @parser.text.should == "Foo\nBar"
+    end
+  end
+
+  describe '#raw_text' do
+    it "should return the entire original data" do
+      data = "Foo\n@param foo x y z\nBar"
+      parse(data)
+      @parser.raw_text.should == data
+    end
+  end
+
+  describe '#tags' do
+    it "should return the parsed tags" do
+      data = "Foo\n@param foo x y z\nBar"
+      parse(data)
+      @parser.tags.size.should == 1
+      @parser.tags.first.tag_name.should == 'param'
+    end
+  end
+
+  describe '#directives' do
+    it "should group all processed directives" do
+      data = "Foo\n@!scope class\n@!visibility private\nBar"
+      parse(data)
+      dirs = @parser.directives
+      dirs.size == 2
+      dirs[0].should be_a(Tags::ScopeDirective)
+      dirs[0].tag.text.should == 'class'
+      dirs[1].should be_a(Tags::VisibilityDirective)
+      dirs[1].tag.text.should == 'private'
+    end
+  end
+
+  describe '#state' do
+    it "should handle modified state" do
+      parse("@!scope class")
+      @parser.state.scope.should == :class
+    end
+  end
+
+  describe 'after_parse' do
+    it "should allow specifying of callbacks" do
+      parser = DocstringParser.new
+      the_yielded_obj = nil
+      DocstringParser.after_parse {|obj| the_yielded_obj = obj }
+      parser.parse("Some text")
+      the_yielded_obj.should == parser
+    end
+  end
+end