yard 0.7.5 → 0.8.0

data/spec/docstring_spec.rb

@@ -2,19 +2,19 @@ require File.dirname(__FILE__) + '/spec_helper'
 
 describe YARD::Docstring do
   before { YARD::Registry.clear }
-  
+
   describe '#initialize' do
     it "should handle docstrings with empty newlines" do
       Docstring.new("\n\n").should == ""
     end
   end
-  
+
   describe '#+' do
     it "should add another Docstring" do
       d = Docstring.new("FOO") + Docstring.new("BAR")
       d.should == "FOO\nBAR"
     end
-    
+
     it "should copy over tags" do
       d1 = Docstring.new("FOO\n@api private\n")
       d2 = Docstring.new("BAR\n@param foo descr")
@@ -22,31 +22,31 @@ describe YARD::Docstring do
       d.should have_tag(:api)
       d.should have_tag(:param)
     end
-      
+
     it "should add a String" do
       d = Docstring.new("FOO") + "BAR"
       d.should == "FOOBAR"
     end
   end
-  
+
   describe '#line' do
     it "should return nil if #line_range is not set" do
       Docstring.new('foo').line.should be_nil
     end
-    
+
     it "should return line_range.first if #line_range is set" do
       doc = Docstring.new('foo')
       doc.line_range = (1..10)
       doc.line.should == doc.line_range.first
     end
   end
-  
+
   describe '#summary' do
     it "should handle empty docstrings" do
       o1 = Docstring.new
       o1.summary.should == ""
     end
-  
+
     it "should handle multiple calls" do
       o1 = Docstring.new("Hello. world")
       5.times { o1.summary.should == "Hello." }
@@ -72,26 +72,26 @@ describe YARD::Docstring do
     it "should not double the ending period" do
       o = Docstring.new("Returns a list of tags specified by +name+ or all tags if +name+ is not specified.\n\nTest")
       o.summary.should == "Returns a list of tags specified by +name+ or all tags if +name+ is not specified."
-  
+
       doc = Docstring.new(<<-eof)
-      
+
         Returns a list of tags specified by +name+ or all tags if +name+ is not specified.
-      
+
         @param name the tag name to return data for, or nil for all tags
         @return [Array<Tags::Tag>] the list of tags by the specified tag name
       eof
       doc.summary.should == "Returns a list of tags specified by +name+ or all tags if +name+ is not specified."
     end
-    
+
     it "should handle references embedded in summary" do
       Docstring.new("Aliasing {Test.test}. Done.").summary.should == "Aliasing {Test.test}."
     end
-    
+
     it "should only end first sentence when outside parentheses" do
       Docstring.new("Hello (the best.) world. Foo bar.").summary.should == "Hello (the best.) world."
       Docstring.new("A[b.]c.").summary.should == "A[b.]c."
     end
-    
+
     it "should only see '.' as period if whitespace (or eof) follows" do
       Docstring.new("hello 1.5 times.").summary.should == "hello 1.5 times."
       Docstring.new("hello... me").summary.should == "hello..."
@@ -115,12 +115,12 @@ describe YARD::Docstring do
       doc.ref_tags.first.tag_name.should == "param"
       doc.ref_tags.first.name.should == "blah"
     end
-  
+
     it "should fail to parse named reference tag into ref_tags" do
       doc = Docstring.new("@param blah THIS_BREAKS_REFTAG (see Foo#bar)")
       doc.ref_tags.size.should == 0
     end
-  
+
     it "should return all valid reference tags along with #tags" do
       o = CodeObjects::MethodObject.new(:root, 'Foo#bar')
       o.docstring.add_tag Tags::Tag.new('return', 'testing')
@@ -131,7 +131,7 @@ describe YARD::Docstring do
       tags.first.should be_kind_of(Tags::RefTag)
       tags.first.owner.should == o
     end
-  
+
     it "should return all valid named reference tags along with #tags(name)" do
       o = CodeObjects::MethodObject.new(:root, 'Foo#bar')
       o.docstring.add_tag Tags::Tag.new('param', 'testing', nil, '*args')
@@ -149,14 +149,14 @@ describe YARD::Docstring do
       tags = doc.tags('param')
       tags.size.should == 0
     end
-    
+
     it "resolves references to methods in the same class with #methname" do
       klass = CodeObjects::ClassObject.new(:root, "Foo")
       o = CodeObjects::MethodObject.new(klass, "bar")
       ref = CodeObjects::MethodObject.new(klass, "baz")
       o.docstring.add_tag Tags::Tag.new('param', 'testing', nil, 'arg1')
       ref.docstring = "@param (see #bar)"
-      
+
       tags = ref.docstring.tags("param")
       tags.size.should == 1
       tags.first.text.should == "testing"
@@ -164,7 +164,7 @@ describe YARD::Docstring do
       tags.first.owner.should == o
     end
   end
-  
+
   describe '#empty?/#blank?' do
     before(:all) do
       Tags::Library.define_tag "Invisible", :invisible_tag
@@ -194,132 +194,19 @@ describe YARD::Docstring do
       d.should be_empty
       d.should_not be_blank
     end
-    
+
     it "should be blank if it has no visible tags" do
       d = Docstring.new("@invisible_tag value")
       d.should be_blank
     end
-    
+
     it "should not be blank if it has invisible tags and only_visible_tags = false" do
       d = Docstring.new("@invisible_tag value")
       d.add_tag Tags::Tag.new('invisible_tag', nil, nil)
       d.blank?(false).should == false
     end
   end
-  
-  describe '#add_tag' do
-    it "should only parse tags with charset [A-Za-z_]" do
-      doc = Docstring.new
-      valid = %w( @testing @valid @is_a @is_A @__ )
-      invalid = %w( @ @return@ @param, @x.y @x-y )
-
-      log.enter_level(Logger::FATAL) do
-        {valid => 1, invalid => 0}.each do |tags, size|
-          tags.each do |tag|
-            class << doc
-              def create_tag(tag_name, *args)
-                add_tag Tags::Tag.new(tag_name, *args)
-              end
-            end
-            doc.all = tag
-            doc.tags(tag[1..-1]).size.should == size
-          end
-        end
-      end
-    end
-  end
-  
-  describe '#parse_comments' do
-    it "should parse comments into tags" do
-      doc = Docstring.new(<<-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.new(<<-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.new(<<-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.new(<<-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.new(<<-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.new(<<-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.new("@hello world")
-    end
-    
-    it "should not add trailing whitespace to freeform tags" do
-      doc = Docstring.new("@api private   \t   ")
-      doc.tag(:api).text.should == "private"
-    end
-  end
-  
   describe '#delete_tags' do
     it "should delete tags by a given tag name" do
       doc = Docstring.new("@param name x\n@param name2 y\n@return foo")
@@ -327,7 +214,7 @@ eof
       doc.tags.size.should == 1
     end
   end
-  
+
   describe '#delete_tag_if' do
     it "should delete tags for a given block" do
       doc = Docstring.new("@param name x\n@param name2 y\n@return foo")
@@ -335,43 +222,43 @@ eof
       doc.tags.size.should == 2
     end
   end
-  
+
   describe '#to_raw' do
     it "should return a clean representation of tags" do
       doc = Docstring.new("Hello world\n@return [String, X] foobar\n@param name<Array> the name\nBYE!")
       doc.to_raw.should == "Hello world\nBYE!\n@param [Array] name\n  the name\n@return [String, X] foobar"
     end
-    
+
     it "should handle tags with newlines and indentation" do
       doc = Docstring.new("@example TITLE\n  the \n  example\n  @foo\n@param [X] name\n  the name")
       doc.to_raw.should == "@example TITLE\n  the \n  example\n  @foo\n@param [X] name\n  the name"
     end
-    
+
     it "should handle deleted tags" do
       doc = Docstring.new("@example TITLE\n  the \n  example\n  @foo\n@param [X] name\n  the name")
       doc.delete_tags(:param)
       doc.to_raw.should == "@example TITLE\n  the \n  example\n  @foo"
     end
-    
+
     it "should handle added tags" do
       doc = Docstring.new("@example TITLE\n  the \n  example\n  @foo")
       doc.add_tag(Tags::Tag.new('foo', 'foo'))
       doc.to_raw.should == "@example TITLE\n  the \n  example\n  @foo\n@foo foo"
     end
-    
+
     it "should be equal to .all if not modified" do
       doc = Docstring.new("123\n@param")
       doc.to_raw.should == doc.all
     end
   end
-  
+
   describe '#dup' do
     it "should duplicate docstring text" do
       doc = Docstring.new("foo")
       doc.dup.should == doc
       doc.dup.all.should == doc
     end
-    
+
     it "should duplicate tags to new list" do
       doc = Docstring.new("@param x\n@return y")
       doc2 = doc.dup
@@ -379,18 +266,18 @@ eof
       doc.tags.size.should == 2
       doc2.tags.size.should == 1
     end
-    
+
     it "should preserve summary" do
       doc = Docstring.new("foo. bar")
       doc.dup.summary.should == doc.summary
     end
-    
+
     it "should preserve hash_flag" do
       doc = Docstring.new
       doc.hash_flag = 'foo'
       doc.dup.hash_flag.should == doc.hash_flag
     end
-    
+
     it "should preserve line_range" do
       doc = Docstring.new
       doc.line_range = (1..2)

data/spec/handlers/alias_handler_spec.rb

@@ -6,40 +6,40 @@ describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}AliasHandler"
   it "should throw alias into namespace object list" do
     P(:A).aliases[P("A#b")].should == :a
   end
-  
+
   ['c', 'd?', '[]', '[]=', '-@', '%', '*'].each do |a|
     it "should handle the Ruby 'alias' keyword syntax for method ##{a}" do
       P('A#' + a).should be_instance_of(CodeObjects::MethodObject)
     end
   end
-  
+
   it "should handle keywords as the alias name" do
     P('A#for').should be_instance_of(CodeObjects::MethodObject)
   end
-  
+
   it "should allow ConstantNames to be specified as aliases" do
     P('A#ConstantName').should be_instance_of(CodeObjects::MethodObject)
   end
-  
+
   it "should create a new method object for the alias" do
     P("A#b").should be_instance_of(CodeObjects::MethodObject)
   end
-  
+
   it "should pull the method into the current class if it's from another one" do
     P(:B).aliases[P("B#q")].should == :x
     P(:B).aliases[P("B#r?")].should == :x
   end
-  
+
   it "should gracefully fail to pull a method in if the original method cannot be found" do
     P(:B).aliases[P("B#s")].should == :to_s
   end
-  
+
   it "should allow complex Ruby expressions after the alias parameters" do
     P(:B).aliases[P("B#t")].should == :inspect
   end
-  
+
   it "should show up in #is_alias? for method" do
-    P("B#t").is_alias?.should == true 
+    P("B#t").is_alias?.should == true
     P('B#r?').is_alias?.should == true
   end
 
@@ -47,31 +47,31 @@ describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}AliasHandler"
     P('B#<<').should be_instance_of(CodeObjects::MethodObject)
     P('B#for').should be_instance_of(CodeObjects::MethodObject)
   end
-  
+
   it "should handle keywords in alias names" do
     P('B#do').is_alias?.should == true
     P('B#x2').is_alias?.should == true
     P(:B).aliases[P('B#do')].should == :x
     P(:B).aliases[P('B#x2')].should == :do
   end
-  
+
   it "should handle quoted symbols" do
     foo = Registry.at('A#foo')
     foo.should_not be_nil
     foo.should be_is_alias
     Registry.at('A').aliases[foo].should == :a
   end
-  
+
   it "should prepend aliases object's docstring to comments" do
     Registry.at('D#a').tag(:return).types.should == ['Numeric']
     Registry.at('D#b').tag(:return).types.should == ['String']
     Registry.at('D#b').docstring.should == "Foo bar"
   end
-  
+
   it "should raise an UndocumentableError if only one parameter is passed" do
     undoc_error "alias_method :q"
   end
-  
+
   it "should raise an UndocumentableError if the parameter is not a Symbol or String" do
     undoc_error "alias_method CONST, Something"
     undoc_error "alias_method variable, ClassName"

data/spec/handlers/attribute_handler_spec.rb

@@ -2,84 +2,84 @@ require File.dirname(__FILE__) + '/spec_helper'
 
 describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}AttributeHandler" do
   before(:all) { parse_file :attribute_handler_001, __FILE__ }
-  
+
   def read_write(namespace, name, read, write, scope = :instance)
     rname, wname = namespace.to_s+"#"+name.to_s, namespace.to_s+"#"+name.to_s+"="
     if read
-      Registry.at(rname).should be_instance_of(CodeObjects::MethodObject) 
+      Registry.at(rname).should be_instance_of(CodeObjects::MethodObject)
     else
       Registry.at(rname).should == nil
     end
-    
+
     if write
-      Registry.at(wname).should be_kind_of(CodeObjects::MethodObject) 
+      Registry.at(wname).should be_kind_of(CodeObjects::MethodObject)
     else
       Registry.at(wname).should == nil
-    end     
-    
+    end
+
     attrs = Registry.at(namespace).attributes[scope][name]
     attrs[:read].should == (read ? Registry.at(rname) : nil)
     attrs[:write].should == (write ? Registry.at(wname) : nil)
   end
-  
+
   it "should parse attributes inside modules too" do
     Registry.at("A#x=").should_not == nil
   end
-  
+
   it "should parse 'attr'" do
     read_write(:B, :a, true, true)
     read_write(:B, :a2, true, false)
     read_write(:B, "a3", true, false)
   end
-  
+
   it "should parse 'attr_reader'" do
     read_write(:B, :b, true, false)
   end
-  
+
   it "should parse 'attr_writer'" do
     read_write(:B, :e, false, true)
   end
-  
+
   it "should parse 'attr_accessor'" do
     read_write(:B, :f, true, true)
   end
-  
+
   it "should parse a list of attributes" do
     read_write(:B, :b, true, false)
     read_write(:B, :c, true, false)
     read_write(:B, :d, true, false)
   end
-  
+
   it "should have a default docstring if one is not supplied" do
     Registry.at("B#f=").docstring.should_not be_empty
   end
-  
+
   it "should set the correct docstring if one is supplied" do
     Registry.at("B#b").docstring.should == "Docstring"
     Registry.at("B#c").docstring.should == "Docstring"
     Registry.at("B#d").docstring.should == "Docstring"
   end
-  
+
   it "should be able to differentiate between class and instance attributes" do
     P('B').class_attributes[:z][:read].scope.should == :class
     P('B').instance_attributes[:z][:read].scope.should == :instance
   end
-  
+
   it "should respond true in method's #is_attribute?" do
     P('B#a').is_attribute?.should == true
     P('B#a=').is_attribute?.should == true
   end
-  
+
   it "should not return true for #is_explicit? in created methods" do
     Registry.at(:B).meths.each do |meth|
       meth.is_explicit?.should == false
     end
   end
-  
+
   it "should handle attr call with no arguments" do
     lambda { StubbedSourceParser.parse_string "attr" }.should_not raise_error
   end
-  
+
   it "should add existing reader method as part of attr_writer combo" do
     Registry.at('C#foo=').attr_info[:read].should == Registry.at('C#foo')
   end
@@ -87,7 +87,7 @@ describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}AttributeHandl
   it "should add existing writer method as part of attr_reader combo" do
     Registry.at('C#foo').attr_info[:write].should == Registry.at('C#foo=')
   end
-  
+
   it "should maintain visibility for attr_reader" do
     Registry.at('D#parser').visibility.should == :protected
   end