yard 0.2.3 → 0.2.3.2

data/lib/yard/parser/ruby/ast_node.rb

@@ -9,8 +9,9 @@ module YARD
       
       class AstNode < Array
         attr_accessor :type, :parent, :docstring, :file, :full_source, :source
-        attr_accessor :source_range, :line_range
+        attr_accessor :source_range, :line_range, :docstring_range
         alias comments docstring
+        alias comments_range docstring_range
         alias to_s source
         
         KEYWORDS = { class: true, alias: true, lambda: true, do_block: true,

data/lib/yard/parser/ruby/legacy/ruby_lex.rb

@@ -11,7 +11,7 @@ module YARD
       EXPR_FNAME = :EXPR_FNAME
       EXPR_DOT   = :EXPR_DOT
       EXPR_CLASS = :EXPR_CLASS
-  
+      
       class Token
         NO_TEXT = "??".freeze
         attr :text
@@ -32,6 +32,14 @@ module YARD
         attr_reader :line_no, :char_no, :text
         attr_accessor :lex_state
       end
+      
+      class TkBlockContents < Token
+        def text; '...' end
+      end
+      
+      class TkStatementEnd < Token
+        def text; '' end
+      end
 
       class TkNode < Token
         attr :node

data/lib/yard/parser/ruby/legacy/statement.rb

@@ -2,6 +2,7 @@ module YARD
   module Parser::Ruby::Legacy
     class Statement 
       attr_reader :tokens, :comments, :block
+      attr_accessor :comments_range
 
       def initialize(tokens, block = nil, comments = nil)
         @tokens = tokens
@@ -9,16 +10,22 @@ module YARD
         @comments = comments
       end
       
+      def first_line
+        to_s(false)
+      end
+      
+      def to_s(include_block = true)
+        tokens.map do |token|
+          RubyToken::TkBlockContents === token ? block.to_s : token.text
+        end.join
+      end
+      alias source to_s
+      
       def inspect
-        buf = [""]
-        tokens.each do |tk|
-          if tk.is_a?(RubyToken::TkNL)
-            buf.push ""
-          else
-            buf.last << tk.text
-          end
-        end
-        buf.map {|text| "\t#{line}: #{text}" }.join("\n")
+        l = line - 1
+        to_s.split(/\n/).map do |text|
+          "\t#{l += 1}:  #{text}"
+        end.join("\n")
       end
       alias show inspect
       
@@ -27,14 +34,15 @@ module YARD
       end
 
       private
-        def clean_tokens(tokens)
-          last_tk = nil
-          tokens.reject do |tk| 
-            tk.is_a?(RubyToken::TkNL) || 
-            (last_tk.is_a?(RubyToken::TkSPACE) && 
-            last_tk.class == tk.class) && last_tk = tk 
-          end
+
+      def clean_tokens(tokens)
+        last_tk = nil
+        tokens.reject do |tk| 
+          tk.is_a?(RubyToken::TkNL) || 
+          (last_tk.is_a?(RubyToken::TkSPACE) && 
+          last_tk.class == tk.class) && last_tk = tk 
         end
+      end
     end
   end
 end

data/lib/yard/parser/ruby/legacy/statement_list.rb

@@ -42,8 +42,10 @@ module YARD
         @state = :first_statement
         @statement_stack = []
         @level = 0
+        @block_num = 0
         @done = false
         @current_block = nil
+        @comments_line = nil
         @statement, @block, @comments = TokenList.new, nil, nil
         @last_tk, @last_ns_tk, @before_last_tk = nil, nil, nil
 
@@ -59,17 +61,56 @@ module YARD
         # If there is no code in the block, return nil
         @comments = @comments.compact if @comments
         if @block || !@statement.empty?
-          Statement.new(@statement, @block, @comments)
+          sanitize_statement_end
+          sanitize_block
+          @statement.pop if [TkNL, TkSPACE, TkSEMICOLON].include?(@statement.last.class)
+          stmt = Statement.new(@statement, @block, @comments)
+          if @comments && @comments_line
+            stmt.comments_range = (@comments_line..(@comments_line + @comments.size - 1))
+          end
+          stmt
         else
           nil
         end
       end
+      
+      def sanitize_statement_end
+        extra = []
+        (@statement.size - 1).downto(0) do |index|
+          token = @statement[index]
+          if TkStatementEnd === token
+            while [TkNL, TkSPACE, TkSEMICOLON].include?(@statement[index - 1].class)
+              extra.unshift(@statement.delete_at(index - 1))
+              index -= 1
+            end
+            @statement.insert(index + 1, *extra)
+            return
+          end
+        end
+      end
+
+      def sanitize_block
+        return unless @block
+        extra = []
+        while [TkSPACE, TkNL, TkSEMICOLON].include?(@block.last.class)
+          next(@block.pop) if TkSEMICOLON === @block.last
+          extra.unshift(@block.pop)
+        end
+
+        @statement.each_with_index do |token, index|
+          if TkBlockContents === token
+            @statement[index, 1] = [token, *extra]
+            return
+          end
+        end
+      end
 
       ##
       # Processes a single token
       #
       # @param [RubyToken::Token] tk the token to process
       def process_token(tk)
+        #p tk.text, @state, @level, @current_block, "<br/>"
         case @state
         when :first_statement
           return if process_initial_comment(tk)
@@ -96,7 +137,8 @@ module YARD
           @current_block = nil
           process_block_token(tk) unless tk.class == TkSEMICOLON
           @state = :block
-        when :block; process_block_token(tk)
+        when :block
+          process_block_token(tk)
         when :post_block
           if tk.class == TkSPACE
             @statement << tk
@@ -113,9 +155,18 @@ module YARD
       #
       # @param [RubyToken::Token] tk the token to process
       def process_block_token(tk)
-        @block << tk
-        return unless balances?(tk)
-        process_statement_end(tk)
+        if balances?(tk)
+          @statement << tk
+          @state = :first_statement
+          process_statement_end(tk)
+        elsif @block_num > 1 || (@block.empty? && [TkSPACE, TkNL].include?(tk.class))
+          @statement << tk
+        else
+          if @block.empty?
+            @statement << TkBlockContents.new(tk.line_no, tk.char_no)
+          end
+          @block << tk
+        end
       end
 
       ##
@@ -132,6 +183,8 @@ module YARD
           @comments = nil
           return
         end
+        
+        @comments_line = tk.line_no unless @comments
 
         # Remove the "#" and up to 1 space before the text
         # Since, of course, the convention is to have "# text"
@@ -153,10 +206,17 @@ module YARD
           # Make sure hashes are parsed as hashes, not as blocks
           (@last_ns_tk.nil? || @last_ns_tk.lex_state != EXPR_BEG)
 
-        @block = TokenList.new
-        @block << tk
         @level += 1
         @state = :block
+        @block_num += 1
+        unless @block
+          @block = TokenList.new
+          tokens = [tk, TkStatementEnd.new(tk.line_no, tk.char_no)]
+          tokens = tokens.reverse if TkBEGIN === tk.class
+          @statement.push(*tokens)
+        else
+          @statement << tk
+        end
 
         true
       end
@@ -210,16 +270,25 @@ module YARD
 
         # Continue with the statement if we've hit a comma in a def
         return if @current_block == TkDEF && peek_no_space.class == TkCOMMA
-
+        
+        
+        if [TkEND_OF_SCRIPT, TkNL, TkSEMICOLON].include?(tk.class) && @state == :block_statement &&
+            [TkRBRACE, TkEND].include?(@last_ns_tk.class) && @level == 0
+          @current_block = nil
+        end
+        
         unless @current_block
           @done = true
           return
         end
 
+        @state = :pre_block
         @level += 1
-        @state = :pre_block unless @stat == :block_statement
-        @block = TokenList.new
-        @block << tk if @current_block && tk.class == TkNL
+        @block_num += 1
+        unless @block
+          @block = TokenList.new
+          @statement << TkStatementEnd.new(tk.line_no, tk.char_no)
+        end
       end
 
       ##
@@ -236,7 +305,7 @@ module YARD
         elsif [TkRPAREN, TkRBRACK, TkRBRACE, TkEND].include?(tk.class) && @level > 0
           @level -= 1
         end
-
+        
         @level == 0
       end
 
@@ -246,7 +315,7 @@ module YARD
       #
       # @param [RubyToken::Token] tk the token to process
       def push_token(tk)
-        @statement << tk unless @level == 0 && [TkNL, TkSEMICOLON, TkCOMMENT].include?(tk.class)
+        @statement << tk unless @level == 0 && [TkCOMMENT].include?(tk.class)
       end
 
       ##

data/lib/yard/parser/ruby/legacy/token_list.rb

@@ -7,8 +7,16 @@ module YARD
         self << content if content
       end
       
-      def to_s
-        collect {|t| t.text }.join
+      def to_s(full_statement = false, show_block = true)
+        inject([]) do |acc, token|
+          break acc if !full_statement && TkStatementEnd === token
+          if !show_block && TkBlockContents === token
+            acc << ""
+          else
+            acc << token.text
+          end
+          acc
+        end.join
       end
       
       # @param [TokenList, Token, String] tokens

data/lib/yard/parser/ruby/ruby_parser.rb

@@ -287,6 +287,7 @@ module YARD
               comment = @comments[line]
               if comment && !comment.empty?
                 node.docstring = comment
+                node.docstring_range = ((line - comment.count("\n"))..line)
                 comments.delete(line)
                 break
               end

data/lib/yard/parser/source_parser.rb

@@ -17,11 +17,7 @@ module YARD
         
         def parse(paths = "lib/**/*.rb", level = log.level)
           log.debug("Parsing #{paths} with `#{parser_type}` parser")
-          if paths.is_a?(Array)
-            files = paths.map {|p| Dir[p] }.flatten
-          else
-            files = Dir[File.join(Dir.pwd, paths)]
-          end
+          files = [paths].flatten.map {|p| p.include?("*") ? Dir[p] : p }.flatten
 
           log.enter_level(level) do
             parse_in_order(*files.uniq)

data/lib/yard/tags/library.rb

@@ -135,7 +135,7 @@ module YARD
       define_tag "Deprecated",        :deprecated
       define_tag "Author",            :author
       define_tag "Raises",            :raise,       :with_types
-      define_tag "See Also",          :see
+      define_tag "See Also",          :see,         :with_name
       define_tag "Since",             :since
       define_tag "Version",           :version
       define_tag "API Visibility",    :api

data/lib/yard/tags/overload_tag.rb

@@ -2,6 +2,7 @@ module YARD
   module Tags
     class OverloadTag < Tag
       attr_reader :signature, :parameters, :docstring
+      undef_method :to_s, :inspect
       
       def initialize(tag_name, text, raw_text)
         super(tag_name, nil)

data/spec/cli/yardoc_spec.rb

@@ -9,6 +9,11 @@ describe YARD::CLI::Yardoc do
     Registry.instance.stub!(:load)
   end
   
+  it "should accept --title" do
+    @yardoc.optparse('--title', 'hello world')
+    @yardoc.options[:title].should == :'hello world'
+  end
+  
   it "should select a markup provider when --markup-provider or -mp is set" do
     @yardoc.optparse("-M", "test")
     @yardoc.options[:markup_provider].should == :test
@@ -40,4 +45,32 @@ describe YARD::CLI::Yardoc do
     @yardoc.options[:serializer].options[:basepath].should == :MYPATH
     @yardoc.files.should == ["FILE1", "FILE2", "FILE3"]
   end
+  
+  it "should accept extra files if specified after '-' with source files" do
+    File.should_receive(:file?).with('extra_file1').and_return(true)
+    File.should_receive(:file?).with('extra_file2').and_return(true)
+    @yardoc.optparse *%w( file1 file2 - extra_file1 extra_file2 )
+    @yardoc.files.should == %w( file1 file2 )
+    @yardoc.options[:files].should == %w( extra_file1 extra_file2 )
+  end
+  
+  it "should accept files section only containing extra files" do
+    @yardoc.optparse *%w( - LICENSE )
+    @yardoc.files.should == %w( lib/**/*.rb )
+    @yardoc.options[:files].should == %w( LICENSE )
+  end
+
+  it "should accept globs as extra files" do
+    Dir.should_receive(:glob).with('*.txt').and_return ['a.txt', 'b.txt']
+    File.should_receive(:file?).with('a.txt').and_return(true)
+    File.should_receive(:file?).with('b.txt').and_return(true)
+    @yardoc.optparse *%w( file1 file2 - *.txt )
+    @yardoc.files.should == %w( file1 file2 )
+    @yardoc.options[:files].should == %w( a.txt b.txt )
+  end
+  
+  it "should accept no params and parse lib/**/*.rb" do
+    @yardoc.optparse
+    @yardoc.files.should == %w( lib/**/*.rb )
+  end
 end

data/spec/docstring_spec.rb

@@ -25,6 +25,10 @@ describe YARD::Docstring do
     end
   end
   
+  it "should handle docstrings with empty newlines" do
+    Docstring.new("\n\n").should == ""
+  end
+  
   it "should handle empty docstrings with #summary" do
     o1 = Docstring.new
     o1.summary.should == ""
@@ -60,6 +64,26 @@ describe YARD::Docstring do
     eof
     doc.summary.should == "Returns a list of tags specified by +name+ or all tags if +name+ is not specified."
   end
+
+  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
   
   it "should parse reference tag into ref_tags" do
     doc = Docstring.new("@return (see Foo#bar)")

data/spec/generators/helpers/html_helper_spec.rb

@@ -1,130 +1,132 @@
 require File.dirname(__FILE__) + '/../../spec_helper'
 
-describe YARD::Generators::Helpers::HtmlHelper, "basic HTML methods" do
+describe YARD::Generators::Helpers::HtmlHelper do
   include YARD::Generators::Helpers::HtmlHelper
-  
-  it "should use #h to escape HTML" do
-    h('Usage: foo "bar" <baz>').should == "Usage: foo &quot;bar&quot; &lt;baz&gt;"
+
+  describe '#h' do
+    it "should use #h to escape HTML" do
+      h('Usage: foo "bar" <baz>').should == "Usage: foo &quot;bar&quot; &lt;baz&gt;"
+    end
   end
   
-  it "should use #fix_typewriter to convert +text+ to <tt>text</tt>" do
-    fix_typewriter("Some +typewriter text+.").should == "Some <tt>typewriter text</tt>."
-    fix_typewriter("Not +typewriter text.").should == "Not +typewriter text."
-    fix_typewriter("Alternating +type writer+ text +here+.").should == "Alternating <tt>type writer</tt> text <tt>here</tt>."
-    fix_typewriter("No ++problem.").should == "No ++problem."
-    fix_typewriter("Math + stuff +is ok+").should == "Math + stuff <tt>is ok</tt>"
+  describe '#fix_typewriter' do
+    it "should use #fix_typewriter to convert +text+ to <tt>text</tt>" do
+      fix_typewriter("Some +typewriter text+.").should == "Some <tt>typewriter text</tt>."
+      fix_typewriter("Not +typewriter text.").should == "Not +typewriter text."
+      fix_typewriter("Alternating +type writer+ text +here+.").should == "Alternating <tt>type writer</tt> text <tt>here</tt>."
+      fix_typewriter("No ++problem.").should == "No ++problem."
+      fix_typewriter("Math + stuff +is ok+").should == "Math + stuff <tt>is ok</tt>"
+    end
   end
-end
-
-describe YARD::Generators::Helpers::HtmlHelper, "#link_object" do
-  include YARD::Generators::Helpers::HtmlHelper
   
-  it "should return the object path if there's no serializer and no title" do
-    stub!(:serializer).and_return nil
-    link_object(CodeObjects::NamespaceObject.new(nil, :YARD)).should == "YARD"
+  describe '#htmlify' do
+    it "should not use hard breaks for textile markup (RedCloth specific)" do
+      htmlify("A\nB", :textile).should_not include("<br")
+    end
   end
+
+  describe "#link_object" do
+    it "should return the object path if there's no serializer and no title" do
+      stub!(:serializer).and_return nil
+      link_object(CodeObjects::NamespaceObject.new(nil, :YARD)).should == "YARD"
+    end
   
-  it "should return the title if there's a title but no serializer" do
-    stub!(:serializer).and_return nil
-    link_object(CodeObjects::NamespaceObject.new(nil, :YARD), 'title').should == "title"
+    it "should return the title if there's a title but no serializer" do
+      stub!(:serializer).and_return nil
+      link_object(CodeObjects::NamespaceObject.new(nil, :YARD), 'title').should == "title"
+    end
   end
-end
 
-describe YARD::Generators::Helpers::HtmlHelper, '#url_for' do
-  include YARD::Generators::Helpers::HtmlHelper
-  
-  before { Registry.clear }
+  describe '#url_for' do
+    before { Registry.clear }
   
-  it "should return nil if serializer is nil" do
-    stub!(:serializer).and_return nil
-    stub!(:current_object).and_return Registry.root
-    url_for(P("Mod::Class#meth")).should be_nil
-  end
+    it "should return nil if serializer is nil" do
+      stub!(:serializer).and_return nil
+      stub!(:current_object).and_return Registry.root
+      url_for(P("Mod::Class#meth")).should be_nil
+    end
   
-  it "should return nil if serializer does not implement #serialized_path" do
-    stub!(:serializer).and_return Serializers::Base.new
-    stub!(:current_object).and_return Registry.root
-    url_for(P("Mod::Class#meth")).should be_nil
-  end
+    it "should return nil if serializer does not implement #serialized_path" do
+      stub!(:serializer).and_return Serializers::Base.new
+      stub!(:current_object).and_return Registry.root
+      url_for(P("Mod::Class#meth")).should be_nil
+    end
   
-  it "should link to a path/file for a namespace object" do
-    stub!(:serializer).and_return Serializers::FileSystemSerializer.new
-    stub!(:current_object).and_return Registry.root
+    it "should link to a path/file for a namespace object" do
+      stub!(:serializer).and_return Serializers::FileSystemSerializer.new
+      stub!(:current_object).and_return Registry.root
     
-    yard = CodeObjects::ModuleObject.new(:root, :YARD)
-    url_for(yard).should == 'YARD.html'
-  end
+      yard = CodeObjects::ModuleObject.new(:root, :YARD)
+      url_for(yard).should == 'YARD.html'
+    end
   
-  it "should link to the object's namespace path/file and use the object as the anchor" do
-    stub!(:serializer).and_return Serializers::FileSystemSerializer.new
-    stub!(:current_object).and_return Registry.root
+    it "should link to the object's namespace path/file and use the object as the anchor" do
+      stub!(:serializer).and_return Serializers::FileSystemSerializer.new
+      stub!(:current_object).and_return Registry.root
     
-    yard = CodeObjects::ModuleObject.new(:root, :YARD)
-    meth = CodeObjects::MethodObject.new(yard, :meth)
-    url_for(meth).should == 'YARD.html#meth-instance_method'
-  end
+      yard = CodeObjects::ModuleObject.new(:root, :YARD)
+      meth = CodeObjects::MethodObject.new(yard, :meth)
+      url_for(meth).should == 'YARD.html#meth-instance_method'
+    end
 
-  it "should properly urlencode methods with punctuation in links" do
-    obj = CodeObjects::MethodObject.new(nil, :/)
-    serializer = mock(:serializer)
-    serializer.stub!(:serialized_path).and_return("file.html")
-    stub!(:serializer).and_return(serializer)
-    stub!(:current_object).and_return(obj)
-    url_for(obj).should == "#%2F-instance_method"
+    it "should properly urlencode methods with punctuation in links" do
+      obj = CodeObjects::MethodObject.new(nil, :/)
+      serializer = mock(:serializer)
+      serializer.stub!(:serialized_path).and_return("file.html")
+      stub!(:serializer).and_return(serializer)
+      stub!(:current_object).and_return(obj)
+      url_for(obj).should == "#%2F-instance_method"
+    end
   end
-end
 
-describe YARD::Generators::Helpers::HtmlHelper, '#anchor_for' do
-  include YARD::Generators::Helpers::HtmlHelper
-  
-  it "should not urlencode data when called directly" do
-    obj = CodeObjects::MethodObject.new(nil, :/)
-    anchor_for(obj).should == "/-instance_method"
+  describe '#anchor_for' do
+    it "should not urlencode data when called directly" do
+      obj = CodeObjects::MethodObject.new(nil, :/)
+      anchor_for(obj).should == "/-instance_method"
+    end
   end
-end
 
-describe YARD::Generators::Helpers::HtmlHelper, '#resolve_links' do
-  include YARD::Generators::Helpers::HtmlHelper
-  
-  def parse_link(link)
-    results = {}
-    link =~ /<a (.+?)>(.+?)<\/a>/
-    params, results[:inner_text] = $1, $2
-    params.split(/\s+/).each do |match|
-      key, value = *match.split('=')
-      results[key.to_sym] = value.gsub(/^["'](.+)["']$/, '\1')
+  describe '#resolve_links' do
+    def parse_link(link)
+      results = {}
+      link =~ /<a (.+?)>(.+?)<\/a>/
+      params, results[:inner_text] = $1, $2
+      params.split(/\s+/).each do |match|
+        key, value = *match.split('=')
+        results[key.to_sym] = value.gsub(/^["'](.+)["']$/, '\1')
+      end
+      results
     end
-    results
-  end
 
-  it "should link static files with file: prefix" do
-    stub!(:serializer).and_return Serializers::FileSystemSerializer.new
-    stub!(:current_object).and_return Registry.root
+    it "should link static files with file: prefix" do
+      stub!(:serializer).and_return Serializers::FileSystemSerializer.new
+      stub!(:current_object).and_return Registry.root
 
-    parse_link(resolve_links("{file:TEST.txt#abc}")).should == {
-      :inner_text => "TEST.txt",
-      :title => "TEST.txt",
-      :href => "TEST.txt.html#abc"
-    }
-    parse_link(resolve_links("{file:TEST.txt title}")).should == {
-      :inner_text => "title",
-      :title => "title",
-      :href => "TEST.txt.html"
-    }
-  end
+      parse_link(resolve_links("{file:TEST.txt#abc}")).should == {
+        :inner_text => "TEST.txt",
+        :title => "TEST.txt",
+        :href => "TEST.txt.html#abc"
+      }
+      parse_link(resolve_links("{file:TEST.txt title}")).should == {
+        :inner_text => "title",
+        :title => "title",
+        :href => "TEST.txt.html"
+      }
+    end
   
-  it "should create regular links with http:// or https:// prefixes" do
-    parse_link(resolve_links("{http://example.com}")).should == {
-      :inner_text => "http://example.com",
-      :target => "_parent",
-      :href => "http://example.com",
-      :title => "http://example.com"
-    }
-    parse_link(resolve_links("{http://example.com title}")).should == {
-      :inner_text => "title",
-      :target => "_parent",
-      :href => "http://example.com",
-      :title => "title"
-    }
+    it "should create regular links with http:// or https:// prefixes" do
+      parse_link(resolve_links("{http://example.com}")).should == {
+        :inner_text => "http://example.com",
+        :target => "_parent",
+        :href => "http://example.com",
+        :title => "http://example.com"
+      }
+      parse_link(resolve_links("{http://example.com title}")).should == {
+        :inner_text => "title",
+        :target => "_parent",
+        :href => "http://example.com",
+        :title => "title"
+      }
+    end
   end
 end