yard 0.6.8 → 0.7.0

data/spec/cli/list_spec.rb

@@ -0,0 +1,8 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe YARD::CLI::List do
+  it "should pass command off to Yardoc with --list" do
+    YARD::CLI::Yardoc.should_receive(:run).with('--list', '--foo')
+    YARD::CLI::List.run('--foo')
+  end
+end

data/spec/cli/yardoc_spec.rb

@@ -40,8 +40,8 @@ describe YARD::CLI::Yardoc do
       @yardoc.use_document_file.should == true
     end
     
-    it "should use lib/**/*.rb and ext/**/*.c as default file glob" do
-      @yardoc.files.should == ['lib/**/*.rb', 'ext/**/*.c']
+    it "should use {lib,app}/**/*.rb and ext/**/*.c as default file glob" do
+      @yardoc.files.should == ['{lib,app}/**/*.rb', 'ext/**/*.c']
     end
     
     it "should use rdoc as default markup type (but falls back on none)" do
@@ -116,6 +116,15 @@ describe YARD::CLI::Yardoc do
       @yardoc.use_yardopts_file.should == true
     end
 
+    should_accept('--yardopts with filename') do |arg|
+      @yardoc = CLI::Yardoc.new
+      File.should_receive(:read_binary).with('.foobar').and_return('')
+      @yardoc.use_document_file = false
+      @yardoc.parse_arguments('--yardopts', '.foobar')
+      @yardoc.use_yardopts_file.should == true
+      @yardoc.options_file.should == '.foobar'
+    end
+
     should_accept('--no-yardopts') do |arg|
       @yardoc = CLI::Yardoc.new
       @yardoc.use_document_file = false
@@ -152,7 +161,7 @@ describe YARD::CLI::Yardoc do
       Templates::Engine.should_not_receive(:generate)
       @yardoc.run(arg)
     end
-    
+        
     should_accept('--exclude') do |arg|
       YARD.should_receive(:parse).with(['a'], ['nota', 'b'])
       @yardoc.run(arg, 'nota', arg, 'b', 'a')
@@ -183,7 +192,7 @@ describe YARD::CLI::Yardoc do
       readme = File.join(File.dirname(__FILE__),'..','..','README.md')
 
       @yardoc.parse_arguments('--main', readme)
-      @yardoc.options[:readme].should == readme
+      @yardoc.options[:readme].should == CodeObjects::ExtraFileObject.new(readme, '')
     end
 
     it "should select a markup provider when --markup-provider or -mp is set" do
@@ -192,6 +201,13 @@ describe YARD::CLI::Yardoc do
       @yardoc.parse_arguments("--markup-provider", "test2")
       @yardoc.options[:markup_provider].should == :test2
     end
+    
+    it "should select a markup format when -m is set" do
+      @yardoc.should_receive(:verify_markup_options).and_return(true)
+      @yardoc.generate = true
+      @yardoc.parse_arguments('-m', 'markdown')
+      @yardoc.options[:markup].should == :markdown
+    end
 
     it "should accept --default-return" do
       @yardoc.parse_arguments *%w( --default-return XYZ )
@@ -387,27 +403,36 @@ describe YARD::CLI::Yardoc do
   
   describe 'Extra file arguments' do
     it "should accept extra files if specified after '-' with source files" do
+      Dir.should_receive(:glob).with('README*').and_return([])
       File.should_receive(:file?).with('extra_file1').and_return(true)
       File.should_receive(:file?).with('extra_file2').and_return(true)
+      File.should_receive(:read).with('extra_file1').and_return('')
+      File.should_receive(:read).with('extra_file2').and_return('')
       @yardoc.parse_arguments *%w( file1 file2 - extra_file1 extra_file2 )
       @yardoc.files.should == %w( file1 file2 )
-      @yardoc.options[:files].should == %w( extra_file1 extra_file2 )
+      @yardoc.options[:files].should == 
+        [CodeObjects::ExtraFileObject.new('extra_file1', ''), 
+          CodeObjects::ExtraFileObject.new('extra_file2', '')]
     end
 
     it "should accept files section only containing extra files" do
       @yardoc.parse_arguments *%w( - LICENSE )
-      @yardoc.files.should == %w( lib/**/*.rb ext/**/*.c )
-      @yardoc.options[:files].should == %w( LICENSE )
+      @yardoc.files.should == %w( {lib,app}/**/*.rb ext/**/*.c )
+      @yardoc.options[:files].should == [CodeObjects::ExtraFileObject.new('LICENSE', '')]
     end
 
     it "should accept globs as extra files" do
       Dir.should_receive(:glob).with('README*').and_return []
       Dir.should_receive(:glob).with('*.txt').and_return ['a.txt', 'b.txt']
+      File.should_receive(:read).with('a.txt').and_return('')
+      File.should_receive(:read).with('b.txt').and_return('')
       File.should_receive(:file?).with('a.txt').and_return(true)
       File.should_receive(:file?).with('b.txt').and_return(true)
       @yardoc.parse_arguments *%w( file1 file2 - *.txt )
       @yardoc.files.should == %w( file1 file2 )
-      @yardoc.options[:files].should == %w( a.txt b.txt )
+      @yardoc.options[:files].should == 
+        [CodeObjects::ExtraFileObject.new('a.txt', ''), 
+          CodeObjects::ExtraFileObject.new('b.txt', '')]
     end
 
     it "should warn if extra file is not found" do
@@ -422,9 +447,9 @@ describe YARD::CLI::Yardoc do
   end
   
   describe 'Source file arguments' do
-    it "should accept no params and parse lib/**/*.rb ext/**/*.c" do
+    it "should accept no params and parse {lib,app}/**/*.rb ext/**/*.c" do
       @yardoc.parse_arguments
-      @yardoc.files.should == %w( lib/**/*.rb ext/**/*.c )
+      @yardoc.files.should == %w( {lib,app}/**/*.rb ext/**/*.c )
     end
   end
   
@@ -529,6 +554,11 @@ describe YARD::CLI::Yardoc do
       @yardoc.options[:markup].should == :rdoc
     end
     
+    it "should load rdoc markup even when no output is specified" do
+      @yardoc.parse_arguments('--no-output')
+      @yardoc.options[:markup].should == :rdoc
+    end
+    
     it "should warn if rdoc cannot be loaded and fallback to :none" do
       mod = YARD::Templates::Helpers::MarkupHelper
       mod.clear_markup_cache
@@ -537,6 +567,24 @@ describe YARD::CLI::Yardoc do
       @yardoc.generate = true
       @yardoc.run
       @yardoc.options[:markup].should == :none
+      mod.clear_markup_cache
+    end
+  end
+  
+  describe '#run' do
+    it "should parse_arguments if run() is called" do
+      @yardoc.should_receive(:parse_arguments)
+      @yardoc.run
+    end
+
+    it "should parse_arguments if run(arg1, arg2, ...) is called" do
+      @yardoc.should_receive(:parse_arguments)
+      @yardoc.run('--private', '-p', 'foo')
+    end
+
+    it "should not parse_arguments if run(nil) is called" do
+      @yardoc.should_not_receive(:parse_arguments)
+      @yardoc.run(nil)
     end
   end
 end

data/spec/code_objects/extra_file_object_spec.rb

@@ -0,0 +1,132 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::CodeObjects::ExtraFileObject do
+  describe '#initialize' do
+    it "should attempt to read contents from filesystem if contents=nil" do
+      File.should_receive(:read).with('file.txt').and_return('')
+      ExtraFileObject.new('file.txt')
+    end
+    
+    it "should raise Errno::ENOENT if contents=nil and file does not exist" do
+      lambda { ExtraFileObject.new('file.txt') }.should raise_error(Errno::ENOENT)
+    end
+    
+    it "should not attempt to read from disk if contents are provided" do
+      ExtraFileObject.new('file.txt', 'CONTENTS')
+    end
+    
+    it "should set filename to filename" do
+      file = ExtraFileObject.new('a/b/c/file.txt', 'CONTENTS')
+      file.filename.should == "a/b/c/file.txt"
+    end
+    
+    it "should parse out attributes at top of the file" do
+      file = ExtraFileObject.new('file.txt', "# @title X\n# @some_attribute Y\nFOO BAR")
+      file.attributes[:title].should == "X"
+      file.attributes[:some_attribute].should == "Y"
+      file.contents.should == "FOO BAR"
+    end
+    
+    it "should allow whitespace prior to '#' marker when parsing attributes" do
+      file = ExtraFileObject.new('file.txt', " \t # @title X\nFOO BAR")
+      file.attributes[:title].should == "X"
+      file.contents.should == "FOO BAR"
+    end
+    
+    it "should parse out old-style #!markup shebang format" do
+      file = ExtraFileObject.new('file.txt', "#!foobar\nHello")
+      file.attributes[:markup].should == "foobar"
+    end
+    
+    it "should not parse old-style #!markup if any whitespace is found" do
+      file = ExtraFileObject.new('file.txt', " #!foobar\nHello")
+      file.attributes[:markup].should be_nil
+      file.contents.should == " #!foobar\nHello"
+    end
+    
+    it "should not parse out attributes if there are newlines prior to attributes" do
+      file = ExtraFileObject.new('file.txt', "\n# @title\nFOO BAR")
+      file.attributes.should be_empty
+      file.contents.should == "\n# @title\nFOO BAR"
+    end
+    
+    it "should set contents to data after attributes" do
+      file = ExtraFileObject.new('file.txt', "# @title\nFOO BAR")
+      file.contents.should == "FOO BAR"
+    end
+    
+    it "should preserve newlines" do
+      file = ExtraFileObject.new('file.txt', "FOO\r\nBAR\nBAZ")
+      file.contents.should == "FOO\r\nBAR\nBAZ"
+    end
+    
+    it "should not include newlines in attribute data" do
+      file = ExtraFileObject.new('file.txt', "# @title FooBar\r\nHello world")
+      file.attributes[:title].should == "FooBar"
+    end
+    
+    it "should force encoding to @encoding attribute if present" do
+      log.should_not_receive(:warn)
+      data = "# @encoding sjis\nFOO"
+      data.force_encoding('binary')
+      file = ExtraFileObject.new('file.txt', data)
+      file.contents.encoding.to_s.should == 'Shift_JIS'
+    end if RUBY19
+
+    it "should warn if @encoding is invalid" do
+      log.should_receive(:warn).with("Invalid encoding `INVALID' in file.txt")
+      data = "# @encoding INVALID\nFOO"
+      encoding = data.encoding
+      file = ExtraFileObject.new('file.txt', data)
+      file.contents.encoding.should == encoding
+    end if RUBY19
+    
+    it "should ignore encoding in 1.8.x (or encoding-unaware platforms)" do
+      log.should_not_receive(:warn)
+      file = ExtraFileObject.new('file.txt', "# @encoding INVALID\nFOO")
+    end if RUBY18
+    
+    it "should attempt to re-parse data as 8bit ascii if parsing fails" do
+      log.should_not_receive(:warn)
+      str = "\xB0"
+      str.force_encoding('utf-8') if str.respond_to?(:force_encoding)
+      file = ExtraFileObject.new('file.txt', str)
+      file.contents.should == "\xB0"
+    end
+  end
+  
+  describe '#name' do
+    it "should be set to basename (not extension) of filename" do
+      file = ExtraFileObject.new('file.txt', '')
+      file.name.should == 'file'
+    end
+  end
+  
+  describe '#title' do
+    it "should return @title attribute if present" do
+      file = ExtraFileObject.new('file.txt', '# @title FOO')
+      file.title.should == 'FOO'
+    end
+    
+    it "should return #name if no @title attribute exists" do
+      file = ExtraFileObject.new('file.txt', '')
+      file.title.should == 'file'
+    end
+  end
+  
+  describe '#==' do
+    it "should define equality on filename alone" do
+      file1 = ExtraFileObject.new('file.txt', 'A')
+      file2 = ExtraFileObject.new('file.txt', 'B')
+      file1.should == file2
+      file1.should be_eql(file2)
+      file1.should be_equal(file2)
+
+      # Another way to test the equality interface
+      a = [file1]
+      a |= [file2]
+      a.size.should == 1
+    end
+    
+  end
+end

data/spec/code_objects/macro_object_spec.rb

@@ -0,0 +1,154 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::CodeObjects::MacroObject do
+  before do 
+    Registry.clear 
+  end
+  
+  describe '.create' do
+    def create(*args) MacroObject.create(*args) end
+
+    it "should create an object" do
+      create('foo', '')
+      obj = Registry.at('.macro.foo')
+      obj.should_not be_nil
+    end
+    
+    it "should use identity map" do
+      obj1 = create('foo', '')
+      obj2 = create('foo', '')
+      obj1.object_id.should == obj2.object_id
+    end
+    
+    it "should allow specifying of macro data" do
+      obj = create('foo', 'MACRODATA')
+      obj.macro_data.should == 'MACRODATA'
+    end
+    
+    it "should attach if a method object is provided" do
+      obj = create('foo', 'MACRODATA', P('Foo.property'))
+      obj.method_object.should == P('Foo.property')
+      obj.should be_attached
+    end
+  end
+  
+  describe '.find' do
+    before { MacroObject.create('foo', 'DATA') }
+    
+    it "should search for an object by name" do
+      MacroObject.find('foo').macro_data.should == 'DATA'
+    end
+    
+    it "should accept Symbol" do
+      MacroObject.find(:foo).macro_data.should == 'DATA'
+    end
+  end
+  
+  describe '.find_or_create' do
+    it "should look up name if @macro is present and find object" do
+      macro1 = MacroObject.create('foo', 'FOO')
+      macro2 = MacroObject.find_or_create("@macro foo\na b c")
+      macro1.should == macro2
+    end
+    
+    it "should create new macro if macro by that name does not exist" do
+      MacroObject.find_or_create("@macro foo\n  @method $1\nEXTRA")
+      MacroObject.find('foo').macro_data.should == "@method $1"
+    end
+    
+    it "should use full docstring if no text block is present in @macro" do
+      MacroObject.find_or_create("@macro foo\n@method $1\nEXTRA")
+      MacroObject.find('foo').macro_data.should == "EXTRA\n@method $1"
+    end
+  end
+  
+  describe '.apply' do
+    before do
+      @args = %w(foo a b c)
+    end
+    
+    def apply(comments)
+      MacroObject.apply(comments, @args)
+    end
+
+    it "should only expand macros if @macro is present" do
+      apply("$1$2$3").should == "$1$2$3"
+    end
+
+    it "should handle macro text inside block" do
+      apply("@macro name\n  foo$1$2$3\nfoobaz").should == "fooabc\nfoobaz"
+    end
+    
+    it "should append docstring to existing macro" do
+      macro = MacroObject.create('name', '$3$2$1')
+      result = MacroObject.apply("@macro name\nfoobar", @args)
+      result.should == "cba\nfoobar"
+    end
+    
+    it "should use only non macro data if docstring is an existing macro" do
+      data = "@macro name\n  $3$2$1\nEXTRA"
+      MacroObject.find_or_create(data)
+      result = MacroObject.apply(data, @args)
+      result.should == "cba\nEXTRA"
+      MacroObject.apply("@macro name\nFOO", @args).should == "cba\nFOO"
+    end
+    
+    it "should create macros if they don't exist" do
+      result = MacroObject.apply("@macro name\n  foo!$1", @args)
+      result.should == "foo!a"
+      MacroObject.find('name').macro_data.should == 'foo!$1'
+    end
+    
+    it "should keep other tags" do
+      apply("@macro name\n  foo$1$2$3\n@param name foo\nfoo").should == 
+        "fooabc\nfoo\n@param name\n  foo"
+    end
+  end
+
+  describe '.expand' do
+    def expand(comments)
+      args = %w(foo a b c)
+      full_line = 'foo :bar, :baz'
+      MacroObject.expand(comments, args, full_line)
+    end
+
+    it "should allow escaping of macro syntax" do
+      expand("$1\\$2$3").should == "a$2c"
+    end
+
+    it "should replace $* with the whole statement" do
+      expand("$* ${*}").should == "foo :bar, :baz foo :bar, :baz"
+    end
+
+    it "should replace $0 with method name" do
+      expand("$0 ${0}").should == "foo foo"
+    end
+
+    it "should replace all $N values with the Nth argument in the method call" do
+      expand("$1$2$3${3}\nfoobar").should == "abcc\nfoobar"
+    end
+
+    it "should replace ${N-M} ranges with N-M arguments (incl. commas)" do
+      expand("${1-2}x").should == "a, bx"
+    end
+
+    it "should handle open ended ranges (${N-})" do
+      expand("${2-}").should == "b, c"
+    end
+
+    it "should handle negative indexes ($-N)" do
+      expand("$-1 ${-2-} ${-2--2}").should == "c b, c b"
+    end
+    
+    it "should accept Docstring objects" do
+      expand(Docstring.new("$1\n@param name foo")).should == "a\n@param name foo"
+    end
+  end
+  
+  describe '#expand' do
+    it "should expand macro given its data" do
+      macro = MacroObject.create_docstring("@macro foo\n  $1 $2 THREE!")
+      macro.expand(['NAME', 'ONE', 'TWO']).should == "ONE TWO THREE!"
+    end
+  end
+end

data/spec/docstring_spec.rb

@@ -29,6 +29,18 @@ describe YARD::Docstring do
     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
@@ -307,4 +319,82 @@ eof
       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")
+      doc.delete_tags(:param)
+      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")
+      doc.delete_tag_if {|t| t.name == 'name2' }
+      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
+      doc2.delete_tags(:param)
+      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)
+      doc.dup.line_range.should == doc.line_range
+    end
+  end
 end