yard 0.8.3 → 0.8.4

data/lib/yard/handlers/base.rb

@@ -1,5 +1,11 @@
 module YARD
   module Handlers
+    # Raise this error when a handler should exit before completing.
+    # The exception will be silenced, allowing the next handler(s) in the
+    # queue to be executed.
+    # @since 0.8.4
+    class HandlerAborted < ::RuntimeError; end
+
     # Raised during processing phase when a handler needs to perform
     # an operation on an object's namespace but the namespace could
     # not be resolved.
@@ -340,6 +346,15 @@ module YARD
       def globals; parser.globals end
       def extra_state; parser.extra_state end
 
+      # Aborts a handler by raising {Handlers::HandlerAborted}.
+      # An exception will only be logged in debugging mode for
+      # this kind of handler exit.
+      #
+      # @since 0.8.4
+      def abort!
+        raise Handlers::HandlerAborted
+      end
+
       # Executes a given block with specific state values for {#owner},
       # {#namespace} and {#scope}.
       #
@@ -473,7 +488,7 @@ module YARD
           next if object.namespace.is_a?(Proxy)
           next unless object.namespace.has_tag?(tag)
           next if object.has_tag?(tag)
-          object.docstring.add_tag(*object.namespace.tags(tag))
+          object.add_tag(*object.namespace.tags(tag))
         end
       end
 
@@ -494,6 +509,7 @@ module YARD
       # @since 0.8.0
       def register_visibility(object, visibility = self.visibility)
         return unless object.respond_to?(:visibility=)
+        return if object.is_a?(NamespaceObject)
         object.visibility = visibility
       end
 
@@ -578,4 +594,4 @@ module YARD
       end
     end
   end
-end
+end

data/lib/yard/handlers/c/handler_methods.rb

@@ -45,7 +45,7 @@ module YARD
           register MethodObject.new(namespace, name, scope) do |obj|
             register_visibility(obj, visibility)
             find_method_body(obj, func_name)
-            obj.docstring.add_tag(Tags::Tag.new(:return, '', 'Boolean')) if name =~ /\?$/
+            obj.add_tag(Tags::Tag.new(:return, '', 'Boolean')) if name =~ /\?$/
           end
         end
 

data/lib/yard/handlers/processor.rb

@@ -112,6 +112,9 @@ module YARD
           find_handlers(stmt).each do |handler|
             begin
               handler.new(self, stmt).process
+            rescue HandlerAborted => abort
+              log.debug "#{handler.to_s} cancelled from #{caller.last}"
+              log.debug "\tin file '#{file}':#{stmt.line}:\n\n" + stmt.show + "\n"
             rescue NamespaceMissingError => missingerr
               log.warn "The #{missingerr.object.type} #{missingerr.object.path} has not yet been recognized."
               log.warn "If this class/method is part of your source tree, this will affect your documentation results."

data/lib/yard/handlers/ruby/class_handler.rb

@@ -5,8 +5,8 @@ class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
   namespace_only
 
   process do
+    classname = statement[0].source.gsub(/\s/, '')
     if statement.type == :class
-      classname = statement[0].source
       superclass = parse_superclass(statement[1])
       if superclass == "Struct"
         is_a_struct = true
@@ -32,7 +32,6 @@ class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
       if statement[0] == s(:var_ref, s(:kw, "self"))
         parse_block(statement[1], :namespace => namespace, :scope => :class)
       else
-        classname = statement[0].source
         proxy = Proxy.new(namespace, classname)
 
         # Allow constants to reference class names

data/lib/yard/handlers/ruby/dsl_handler_methods.rb

@@ -14,6 +14,12 @@ module YARD
 
           @docstring = statement.comments || ""
           @docstring = @docstring.join("\n") if @docstring.is_a?(Array)
+
+          if @docstring =~ /^@!?macro\s+\[[^\]]*attach/
+            register_docstring(nil)
+            @docstring = ""
+          end
+
           if macro = find_attached_macro
             @docstring += "\n" +
               macro.expand([caller_method, *call_params], statement.source)
@@ -59,7 +65,7 @@ module YARD
           Registry.all(:macro).each do |macro|
             next unless macro.method_object
             next unless macro.method_object.name.to_s == caller_method.to_s
-            (namespace.inheritance_tree + [P('Object')]).each do |obj|
+            (namespace.inheritance_tree(true) + [P('Object')]).each do |obj|
               return macro if obj == macro.method_object.namespace
             end
           end

data/lib/yard/handlers/ruby/exception_handler.rb

@@ -21,6 +21,6 @@ class YARD::Handlers::Ruby::ExceptionHandler < YARD::Handlers::Ruby::Base
       end
     end
 
-    owner.docstring.add_tag YARD::Tags::Tag.new(:raise, '', klass) if klass
+    owner.add_tag YARD::Tags::Tag.new(:raise, '', klass) if klass
   end
-end
+end

data/lib/yard/handlers/ruby/legacy/class_handler.rb

@@ -9,12 +9,13 @@ class YARD::Handlers::Ruby::Legacy::ClassHandler < YARD::Handlers::Ruby::Legacy:
       classname = $1
       superclass_def = $2
       superclass = parse_superclass($2)
+      classname = classname.gsub(/\s/, '')
       if superclass == "Struct"
         is_a_struct = true
         superclass = struct_superclass_name(superclass_def)
         create_struct_superclass(superclass, superclass_def)
       end
-      undocsuper = $2 && superclass.nil?
+      undocsuper = superclass_def && superclass.nil?
 
       klass = register ClassObject.new(namespace, classname) do |o|
         o.superclass = superclass if superclass
@@ -30,8 +31,8 @@ class YARD::Handlers::Ruby::Legacy::ClassHandler < YARD::Handlers::Ruby::Legacy:
       if undocsuper
         raise YARD::Parser::UndocumentableError, 'superclass (class was added without superclass)'
       end
-    elsif statement.tokens.to_s =~ /^class\s*<<\s*([\w\:]+)/
-      classname = $1
+    elsif statement.tokens.to_s =~ /^class\s*<<\s*([\w\:\s]+)/
+      classname = $1.gsub(/\s/, '')
       proxy = Proxy.new(namespace, classname)
 
       # Allow constants to reference class names

data/lib/yard/handlers/ruby/legacy/exception_handler.rb

@@ -7,6 +7,6 @@ class YARD::Handlers::Ruby::Legacy::ExceptionHandler < YARD::Handlers::Ruby::Leg
     return if owner.has_tag?(:raise)
 
     klass = statement.tokens.to_s[/^raise[\(\s]*(#{NAMESPACEMATCH})\s*(?:\)|,|\s(?:if|unless|until)|;|(?:(?:\.|\:\:)\s*)?new|$)/, 1]
-    owner.docstring.add_tag YARD::Tags::Tag.new(:raise, '', klass) if klass
+    owner.add_tag YARD::Tags::Tag.new(:raise, '', klass) if klass
   end
-end
+end

data/lib/yard/handlers/ruby/legacy/method_handler.rb

@@ -38,18 +38,18 @@ class YARD::Handlers::Ruby::Legacy::MethodHandler < YARD::Handlers::Ruby::Legacy
 
     if mscope == :instance && meth == "initialize"
       unless obj.has_tag?(:return)
-        obj.docstring.add_tag(YARD::Tags::Tag.new(:return,
+        obj.add_tag(YARD::Tags::Tag.new(:return,
           "a new instance of #{namespace.name}", namespace.name.to_s))
       end
     elsif mscope == :class && obj.docstring.blank? && %w(inherited included
         extended method_added method_removed method_undefined).include?(meth)
-      obj.docstring.add_tag(YARD::Tags::Tag.new(:private, nil))
+      obj.add_tag(YARD::Tags::Tag.new(:private, nil))
     elsif meth.to_s =~ /\?$/
       if obj.tag(:return) && (obj.tag(:return).types || []).empty?
         obj.tag(:return).types = ['Boolean']
       elsif obj.tag(:return).nil?
         unless obj.tags(:overload).any? {|overload| overload.tag(:return) }
-          obj.docstring.add_tag(YARD::Tags::Tag.new(:return, "", "Boolean"))
+          obj.add_tag(YARD::Tags::Tag.new(:return, "", "Boolean"))
         end
       end
     end
@@ -60,7 +60,7 @@ class YARD::Handlers::Ruby::Legacy::MethodHandler < YARD::Handlers::Ruby::Legacy
         expected_param = option.name
         unless obj.tags(:param).find {|x| x.name == expected_param }
           new_tag = YARD::Tags::Tag.new(:param, "a customizable set of options", "Hash", expected_param)
-          obj.docstring.add_tag(new_tag)
+          obj.add_tag(new_tag)
         end
       end
     end

data/lib/yard/handlers/ruby/legacy/yield_handler.rb

@@ -12,17 +12,17 @@ class YARD::Handlers::Ruby::Legacy::YieldHandler < YARD::Handlers::Ruby::Legacy:
       item = item.inspect unless item.is_a?(String)
       if item == "self"
         yieldtag.types << '_self'
-        owner.docstring.add_tag YARD::Tags::Tag.new(:yieldparam,
+        owner.add_tag YARD::Tags::Tag.new(:yieldparam,
           "the object that the method was called on", owner.namespace.path, '_self')
       elsif item == "super"
         yieldtag.types << '_super'
-        owner.docstring.add_tag YARD::Tags::Tag.new(:yieldparam,
+        owner.add_tag YARD::Tags::Tag.new(:yieldparam,
           "the result of the method from the superclass", nil, '_super')
       else
         yieldtag.types << item
       end
     end
 
-    owner.docstring.add_tag(yieldtag) unless yieldtag.types.empty?
+    owner.add_tag(yieldtag) unless yieldtag.types.empty?
   end
-end
+end

data/lib/yard/handlers/ruby/method_handler.rb

@@ -29,20 +29,20 @@ class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
       nobj.aliases.delete(aobj)
     end if nobj.is_a?(NamespaceObject)
 
-    if mscope == :instance && meth == "initialize"
+    if obj.constructor?
       unless obj.has_tag?(:return)
-        obj.docstring.add_tag(YARD::Tags::Tag.new(:return,
+        obj.add_tag(YARD::Tags::Tag.new(:return,
           "a new instance of #{namespace.name}", namespace.name.to_s))
       end
     elsif mscope == :class && obj.docstring.blank? && %w(inherited included
         extended method_added method_removed method_undefined).include?(meth)
-      obj.docstring.add_tag(YARD::Tags::Tag.new(:private, nil))
+      obj.add_tag(YARD::Tags::Tag.new(:private, nil))
     elsif meth.to_s =~ /\?$/
       if obj.tag(:return) && (obj.tag(:return).types || []).empty?
         obj.tag(:return).types = ['Boolean']
       elsif obj.tag(:return).nil?
         unless obj.tags(:overload).any? {|overload| overload.tag(:return) }
-          obj.docstring.add_tag(YARD::Tags::Tag.new(:return, "", "Boolean"))
+          obj.add_tag(YARD::Tags::Tag.new(:return, "", "Boolean"))
         end
       end
     end
@@ -53,7 +53,7 @@ class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
         expected_param = option.name
         unless obj.tags(:param).find {|x| x.name == expected_param }
           new_tag = YARD::Tags::Tag.new(:param, "a customizable set of options", "Hash", expected_param)
-          obj.docstring.add_tag(new_tag)
+          obj.add_tag(new_tag)
         end
       end
     end
@@ -88,4 +88,4 @@ class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
       "def #{method_name}"
     end
   end
-end
+end

data/lib/yard/handlers/ruby/struct_handler_methods.rb

@@ -63,7 +63,7 @@ module YARD::Handlers::Ruby::StructHandlerMethods
     return_type = return_type_from_tag(member_tag)
     getter_doc_text = member_tag ? member_tag.text : "Returns the value of attribute #{member}"
     new_method.docstring.replace(getter_doc_text)
-    new_method.docstring.add_tag YARD::Tags::Tag.new(:return, "the current value of #{member}", return_type)
+    new_method.add_tag YARD::Tags::Tag.new(:return, "the current value of #{member}", return_type)
   end
 
   # Creates the auto-generated docstring for the setter method of a struct's
@@ -78,8 +78,8 @@ module YARD::Handlers::Ruby::StructHandlerMethods
     return_type = return_type_from_tag(member_tag)
     setter_doc_text = member_tag ? member_tag.text : "Sets the attribute #{member}"
     new_method.docstring.replace(setter_doc_text)
-    new_method.docstring.add_tag YARD::Tags::Tag.new(:param, "the value to set the attribute #{member} to.", return_type, "value")
-    new_method.docstring.add_tag YARD::Tags::Tag.new(:return, "the newly set value", return_type)
+    new_method.add_tag YARD::Tags::Tag.new(:param, "the value to set the attribute #{member} to.", return_type, "value")
+    new_method.add_tag YARD::Tags::Tag.new(:return, "the newly set value", return_type)
   end
 
   # Creates and registers a class object with the given name and superclass name.
@@ -138,4 +138,4 @@ module YARD::Handlers::Ruby::StructHandlerMethods
       create_reader klass, member if create_member_method?(klass, member, :read)
     end
   end
-end
+end

data/lib/yard/handlers/ruby/yield_handler.rb

@@ -13,11 +13,11 @@ class YARD::Handlers::Ruby::YieldHandler < YARD::Handlers::Ruby::Base
       statement.jump(:list).children.each do |item|
         if item == s(:var_ref, s(:kw, "self"))
           yieldtag.types << '_self'
-          owner.docstring.add_tag YARD::Tags::Tag.new(:yieldparam,
+          owner.add_tag YARD::Tags::Tag.new(:yieldparam,
             "the object that the method was called on", owner.namespace.path, '_self')
         elsif item == s(:zsuper)
           yieldtag.types << '_super'
-          owner.docstring.add_tag YARD::Tags::Tag.new(:yieldparam,
+          owner.add_tag YARD::Tags::Tag.new(:yieldparam,
             "the result of the method from the superclass", nil, '_super')
         else
           yieldtag.types << item.source
@@ -25,6 +25,6 @@ class YARD::Handlers::Ruby::YieldHandler < YARD::Handlers::Ruby::Base
       end
     end
 
-    owner.docstring.add_tag(yieldtag) unless yieldtag.types.empty?
+    owner.add_tag(yieldtag) unless yieldtag.types.empty?
   end
-end
+end

data/lib/yard/i18n/locale.rb

@@ -5,6 +5,22 @@ module YARD
     #
     # @since 0.8.2
     class Locale
+      class << self
+        # @return [String, nil] the default locale name.
+        # @since 0.8.4
+        attr_accessor :default
+
+        undef default
+        def default
+          @@default ||= nil
+        end
+
+        undef default=
+        def default=(locale)
+          @@default = locale
+        end
+      end
+
       # @return [String] the name of the locale. It used IETF language
       #   tag format +[language[_territory][.codeset][@modifier]]+.
       # @see http://tools.ietf.org/rfc/bcp/bcp47.txt

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

@@ -301,6 +301,9 @@ module YARD
            # Or we might be at the beginning of an argument list
            (@current_block == TkDEF && tk.class == TkRPAREN))
 
+        # Continue line ending on . or ::
+        return if @last_tk && [EXPR_DOT].include?(@last_tk.lex_state)
+
         # Continue a possible existing new statement unless we just finished an expression...
         return unless (@last_tk && [EXPR_END, EXPR_ARG].include?(@last_tk.lex_state)) ||
           # Or we've opened a block and are ready to move into the body

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

@@ -217,6 +217,11 @@ module YARD
           lstart, sstart = *(map ? map.pop : [lineno, @ns_charno - 1])
           node.source_range = Range.new(sstart, @ns_charno - 1)
           node.line_range = Range.new(lstart, lineno)
+          if node.respond_to?(:block)
+            sr, lr = node.block.source_range, node.block.line_range
+            node.block.source_range = Range.new(sr.first, @tokens.last[2][1])
+            node.block.line_range = Range.new(lr.first, @tokens.last[2][0])
+          end
           node
         end
 
@@ -241,9 +246,9 @@ module YARD
 
         def add_token(token, data)
           if @tokens.last && @tokens.last[0] == :symbeg
-            @tokens[-1] = [:symbol, ":" + data]
+            @tokens[-1] = [:symbol, ":" + data, @tokens.last[2]]
           elsif @heredoc_state == :started
-            @heredoc_tokens << [token, data]
+            @heredoc_tokens << [token, data, [lineno, charno]]
 
             # fix ripper encoding of heredoc bug
             # (see http://bugs.ruby-lang.org/issues/6200)
@@ -251,12 +256,12 @@ module YARD
 
             @heredoc_state = :ended if token == :heredoc_end
           elsif (token == :nl || token == :comment) && @heredoc_state == :ended
-            @heredoc_tokens.unshift([token, data])
+            @heredoc_tokens.unshift([token, data, [lineno, charno]])
             @tokens += @heredoc_tokens
             @heredoc_tokens = nil
             @heredoc_state = nil
           else
-            @tokens << [token, data]
+            @tokens << [token, data, [lineno, charno]]
             if token == :heredoc_beg
               @heredoc_state = :started
               @heredoc_tokens = []

data/lib/yard/rubygems/doc_manager.rb

@@ -1,5 +1,8 @@
-require 'rubygems/user_interaction'
-require 'rubygems/doc_manager'
+begin
+  require 'rubygems/user_interaction'
+  require 'rubygems/doc_manager'
+rescue LoadError
+end
 
 class Gem::DocManager
   def self.load_yardoc
@@ -34,7 +37,7 @@ class Gem::DocManager
     Dir.chdir(old_pwd)
   end
 
-  undef setup_rdoc
+  begin undef setup_rdoc; rescue NameError; end
   def setup_rdoc
     if File.exist?(@doc_dir) && !File.writable?(@doc_dir) then
       raise Gem::FilePermissionError.new(@doc_dir)
@@ -64,8 +67,11 @@ class Gem::DocManager
     say "Building YARD (yri) index for #{@spec.full_name}..."
     run_yardoc '-c', '-n'
   end
-  alias install_ri_yard_orig install_ri
-  alias install_ri install_ri_yard
+
+  begin
+    alias install_ri_yard_orig install_ri
+    alias install_ri install_ri_yard
+  rescue NameError; end
 
   def install_rdoc_yard
     if @spec.has_rdoc?
@@ -74,6 +80,9 @@ class Gem::DocManager
       install_yardoc
     end
   end
-  alias install_rdoc_yard_orig install_rdoc
-  alias install_rdoc install_rdoc_yard
+
+  begin
+    alias install_rdoc_yard_orig install_rdoc
+    alias install_rdoc install_rdoc_yard
+  rescue NameError; end
 end

data/lib/yard/tags/directives.rb

@@ -266,8 +266,9 @@ module YARD
       end
 
       def attach?
-         class_method? || # always attach to class methods
-          (tag.types && tag.types.include?('attach'))
+        new? && # must have data or there is nothing to attach
+        class_method? || # always attach to class methods
+        (tag.types && tag.types.include?('attach'))
       end
 
       def class_method?

data/lib/yard/tags/overload_tag.rb

@@ -55,7 +55,7 @@ module YARD
           # FIXME refactor this code to not make use of the Handlers::Base class (tokval_list should be moved)
           toks = YARD::Parser::Ruby::Legacy::TokenList.new(args)
           args = YARD::Handlers::Ruby::Legacy::Base.new(nil, nil).send(:tokval_list, toks, :all)
-          args.map! {|a| k, v = *a.split('=', 2); [k.strip.to_sym, (v ? v.strip : nil)] } if args
+          args.map! {|a| k, v = *a.split('=', 2); [k.strip.to_s, (v ? v.strip : nil)] } if args
           @name = meth.to_sym
           @parameters = args
         end

data/lib/yard/templates/helpers/html_helper.rb

@@ -256,6 +256,8 @@ module YARD
           # "CurrentClass.method_name"
           if obj.is_a?(CodeObjects::MethodObject) && obj.scope == :class && obj.parent == object
             title = h([object.name, obj.sep, obj.name].join)
+          elsif obj.title != obj.path
+            title = h(obj.title)
           else
             title = h(object.relative_path(obj))
           end
@@ -266,7 +268,7 @@ module YARD
         return title if obj.is_a?(CodeObjects::Proxy)
 
         link = url_for(obj, anchor, relative)
-        link = link ? link_url(link, title, :title => h("#{obj.path} (#{obj.type})")) : title
+        link = link ? link_url(link, title, :title => h("#{obj.title} (#{obj.type})")) : title
         "<span class='object_link'>" + link + "</span>"
       end
 
@@ -310,6 +312,7 @@ module YARD
       def url_for(obj, anchor = nil, relative = true)
         link = nil
         return link unless serializer
+        return link if obj.is_a?(CodeObjects::Base) && run_verifier([obj]).empty?
 
         if obj.is_a?(CodeObjects::Base) && !obj.is_a?(CodeObjects::NamespaceObject)
           # If the obj is not a namespace obj make it the anchor.
@@ -582,7 +585,7 @@ module YARD
             string = html_syntax_highlight(CGI.unescapeHTML(string), language)
           end
           classes = ['code', language].compact.join(' ')
-          %Q{<pre class="#{classes}"><code>#{string}</code></pre>}
+          %Q{<pre class="#{classes}"><code class="#{language}">#{string}</code></pre>}
         end
       end
     end