yard 0.9.5 → 0.9.6

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

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+module YARD
+  module Parser
+    module Ruby
+      # Supports {#each} enumeration over a source's tokens, yielding
+      # the token and a possible {CodeObjects::Base} associated with the
+      # constant or identifier token.
+      class TokenResolver
+        include Enumerable
+
+        # Creates a token resolver for given source.
+        #
+        # @param source [String] the source code to tokenize
+        # @param namespace [CodeObjects::Base] the object/namespace to resolve from
+        def initialize(source, namespace = Registry.root)
+          @tokens = RubyParser.parse(source, '(tokenize)').tokens
+          raise ParserSyntaxError if @tokens.empty? && !source.empty?
+          @default_namespace = namespace
+        end
+
+        # Iterates over each token, yielding the token and a possible code
+        # object that is associated with the token.
+        #
+        # @yieldparam token [Array(Symbol,String,Array(Integer,Integer))] the
+        #   current token object being iterated
+        # @yieldparam object [CodeObjects::Base, nil] the fully qualified code
+        #   object associated with the current token, or nil if there is no object
+        #   for the yielded token.
+        # @example Yielding code objects
+        #   r = TokenResolver.new("A::B::C")
+        #   r.each do |tok, obj|
+        #     if obj
+        #       puts "#{tok[0]} -> #{obj.path.inspect}"
+        #     else
+        #       puts "No object: #{tok.inspect}"
+        #     end
+        #   end
+        #
+        #   # Prints:
+        #   # :const -> "A"
+        #   # No object: [:op, "::"]
+        #   # :const -> "A::B"
+        #   # No object: [:op, "::"]
+        #   # :const -> "A::B::C"
+        def each
+          @states = []
+          push_state
+          @tokens.each do |token|
+            yield_obj = false
+
+            if skip_group && [:const, :ident, :op, :period].include?(token[0])
+              yield token, nil
+              next
+            else
+              self.skip_group = false
+            end
+
+            case token[0]
+            when :const
+              lookup(token[0], token[1])
+              yield_obj = true
+              self.last_sep = nil
+            when :ident
+              lookup(token[0], token[1])
+              yield_obj = true
+              self.last_sep = nil
+            when :op, :period
+              self.last_sep = token[1]
+              unless CodeObjects.types_for_separator(token[1])
+                self.object = nil
+                self.last_sep = nil
+              end
+            when :lparen
+              push_state
+            when :rparen
+              pop_state
+            else
+              self.object = nil
+            end
+
+            yield token, (yield_obj ? object : nil)
+
+            if next_object
+              self.object = next_object
+              self.next_object = nil
+            end
+            self.skip_group = true if yield_obj && object.nil?
+          end
+        end
+
+        def self.state_attr(*attrs)
+          attrs.each do |attr|
+            define_method(attr) { @states.last[attr.to_sym] }
+            define_method("#{attr}=") {|v| @states.last[attr.to_sym] = v }
+            protected attr, :"#{attr}="
+          end
+        end
+
+        private
+
+        def push_state
+          @states.push :object => nil, :skip_group => false, :last_sep => nil
+        end
+
+        def pop_state
+          @states.pop
+        end
+
+        state_attr :object, :next_object, :skip_group, :last_sep
+
+        def lookup(toktype, name)
+          types = object_resolved_types
+          return self.object = nil if types.empty?
+
+          if toktype == :const
+            types.any? do |type|
+              prefix = (type ? type.path : "") + last_sep.to_s
+              self.object = Registry.resolve(@default_namespace, "#{prefix}#{name}", true)
+            end
+          else # ident
+            types.any? do |type|
+              obj = Registry.resolve(type, name, true)
+              if obj.nil? && name == "new"
+                obj = Registry.resolve(object, "#initialize", true)
+                self.next_object = object if obj.nil?
+              end
+              self.object = obj
+            end
+          end
+        end
+
+        def object_resolved_types(obj = object)
+          return [obj] unless obj.is_a?(CodeObjects::MethodObject)
+
+          resolved_types = []
+          tags = obj.tags(:return)
+          tags += obj.tags(:overload).map {|o| o.tags(:return) }.flatten
+          tags.each do |tag|
+            next if tag.types.nil?
+            tag.types.each do |type|
+              type = type.sub(/<.+>/, '')
+              if type == "self"
+                resolved_types << obj.parent
+              else
+                type_obj = Registry.resolve(obj, type, true)
+                resolved_types << type_obj if type_obj
+              end
+            end
+          end
+
+          resolved_types
+        end
+      end
+    end
+  end
+end

data/lib/yard/parser/source_parser.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'stringio'
 require 'ostruct'
 
@@ -6,7 +7,7 @@ module YARD
     # Raised when an object is recognized but cannot be documented. This
     # generally occurs when the Ruby syntax used to declare an object is
     # too dynamic in nature.
-    class UndocumentableError < Exception; end
+    class UndocumentableError < RuntimeError; end
 
     # Raised when the parser sees a Ruby syntax error
     class ParserSyntaxError < UndocumentableError; end
@@ -39,7 +40,8 @@ module YARD
       #
       # @see Processor#parse_remaining_files
       def parse
-        while file = files.shift
+        until files.empty?
+          file = files.shift
           log.capture("Parsing #{file}") do
             SourceParser.new(SourceParser.parser_type, @global_state).parse(file)
           end
@@ -61,7 +63,7 @@ module YARD
     # @see CodeObjects::Base
     class SourceParser
       SHEBANG_LINE  = /\A\s*#!\S+/
-      ENCODING_LINE = /\A(?:\s*#*!.*\r?\n)?\s*(?:#+|\/\*+|\/\/+).*coding\s*[:=]{1,2}\s*([a-z\d_\-]+)/i
+      ENCODING_LINE = %r{\A(?:\s*#*!.*\r?\n)?\s*(?:#+|/\*+|//+).*coding\s*[:=]{1,2}\s*([a-z\d_\-]+)}i
       FROZEN_STRING_LINE = /frozen(-|_)string(-|_)literal: true/i
 
       # The default glob of files to be parsed.
@@ -71,12 +73,12 @@ module YARD
       # Byte order marks for various encodings
       # @since 0.7.0
       ENCODING_BYTE_ORDER_MARKS = {
-        'utf-8' => "\xEF\xBB\xBF",
+        'utf-8' => String.new("\xEF\xBB\xBF"),
         # Not yet supported
-        #'utf-16be' => "\xFE\xFF",
-        #'utf-16le' => "\xFF\xFE",
-        #'utf-32be' => "\x00\x00\xFF\xFE",
-        #'utf-32le' => "\xFF\xFE",
+        # 'utf-16be' => "\xFE\xFF",
+        # 'utf-16le' => "\xFF\xFE",
+        # 'utf-32be' => "\x00\x00\xFF\xFE",
+        # 'utf-32le' => "\xFF\xFE",
       }
 
       class << self
@@ -105,7 +107,7 @@ module YARD
           end
           files = [paths].flatten.
             map {|p| File.directory?(p) ? "#{p}/**/*.{rb,c,cc,cxx,cpp}" : p }.
-            map {|p| p.include?("*") ? Dir[p].sort_by {|f| f.length } : p }.flatten.
+            map {|p| p.include?("*") ? Dir[p].sort_by {|d| [d.length, d] } : p }.flatten.
             reject {|p| !File.file?(p) || excluded.any? {|re| p =~ re } }
 
           log.enter_level(level) do
@@ -167,7 +169,7 @@ module YARD
         # @return [Symbol] the parser type to be used for the extension
         # @since 0.5.6
         def parser_type_for_extension(extension)
-          type = parser_type_extensions.find do |t, exts|
+          type = parser_type_extensions.find do |_t, exts|
             [exts].flatten.any? {|ext| ext === extension }
           end
           validated_parser_type(type ? type.first : :ruby)
@@ -362,8 +364,8 @@ module YARD
         def parse_in_order(*files)
           global_state = OpenStruct.new
 
-          before_parse_list_callbacks.each do |cb|
-            return if cb.call(files, global_state) == false
+          return if before_parse_list_callbacks.any? do |cb|
+            cb.call(files, global_state) == false
           end
 
           OrderedParser.new(global_state, files).parse
@@ -417,11 +419,11 @@ module YARD
         case content
         when String
           @file = File.cleanpath(content)
-          content = convert_encoding(File.read_binary(file))
+          content = convert_encoding(String.new(File.read_binary(file)))
           checksum = Registry.checksum_for(content)
           return if Registry.checksums[file] == checksum
 
-          if Registry.checksums.has_key?(file)
+          if Registry.checksums.key?(file)
             log.info "File '#{file}' was modified, re-processing..."
           end
           Registry.checksums[@file] = checksum
@@ -474,7 +476,7 @@ module YARD
           content.force_encoding('binary')
           ENCODING_BYTE_ORDER_MARKS.each do |encoding, bom|
             bom.force_encoding('binary')
-            if content[0,bom.size] == bom
+            if content[0, bom.size] == bom
               content.force_encoding(encoding)
               return content
             end
@@ -487,10 +489,13 @@ module YARD
       # Runs a {Handlers::Processor} object to post process the parsed statements.
       # @return [void]
       def post_process
-        return unless @parser.respond_to? :enumerator
-        return unless enumerator = @parser.enumerator
-        post = Handlers::Processor.new(self)
-        post.process(enumerator)
+        return unless @parser.respond_to?(:enumerator)
+
+        enumerator = @parser.enumerator
+        if enumerator
+          post = Handlers::Processor.new(self)
+          post.process(enumerator)
+        end
       end
 
       def parser_type=(value)
@@ -510,7 +515,10 @@ module YARD
       # @since 0.5.6
       def parser_class
         klass = self.class.parser_types[parser_type]
-        raise ArgumentError, "invalid parser type '#{parser_type}' or unrecognized file", caller[1..-1] if !klass
+        unless klass
+          raise ArgumentError, "invalid parser type '#{parser_type}' or unrecognized file", caller[1..-1]
+        end
+
         klass
       end
     end

data/lib/yard/rake/yardoc_task.rb

@@ -1,9 +1,9 @@
+# frozen_string_literal: true
 require 'rake'
 require 'rake/tasklib'
 
 module YARD
   module Rake
-
     # The rake task to run {CLI::Yardoc} and generate documentation.
     class YardocTask < ::Rake::TaskLib
       # The name of the task
@@ -54,9 +54,9 @@ module YARD
         @files = []
 
         yield self if block_given?
-        self.options +=  ENV['OPTS'].split(/[ ,]/) if ENV['OPTS']
+        self.options += ENV['OPTS'].split(/[ ,]/) if ENV['OPTS']
         self.files   += ENV['FILES'].split(/[ ,]/) if ENV['FILES']
-        self.options << '--no-stats' unless self.stats_options.empty?
+        self.options << '--no-stats' unless stats_options.empty?
 
         define
       end

data/lib/yard/registry.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'fileutils'
 require 'digest/sha1'
 
@@ -50,7 +51,7 @@ module YARD
       # @return [nil] if +for_writing+ is set to false and no yardoc file
       #   is found, returns nil.
       def yardoc_file_for_gem(gem, ver_require = ">= 0", for_writing = false)
-        specs = Gem.source_index.find_name(gem, ver_require)
+        specs = YARD::GemIndex.find_all_by_name(gem, ver_require)
         return if specs.empty?
 
         result = nil
@@ -63,12 +64,12 @@ module YARD
 
           if for_writing
             result = global_yardoc_file(spec, for_writing) ||
-              old_global_yardoc_file(spec, for_writing) ||
-              local_yardoc_file(spec, for_writing)
+                     old_global_yardoc_file(spec, for_writing) ||
+                     local_yardoc_file(spec, for_writing)
           else
             result = local_yardoc_file(spec, for_writing) ||
-              global_yardoc_file(spec, for_writing) ||
-              old_global_yardoc_file(spec, for_writing)
+                     global_yardoc_file(spec, for_writing) ||
+                     old_global_yardoc_file(spec, for_writing)
           end
 
           break if result
@@ -83,6 +84,7 @@ module YARD
       attr_accessor :yardoc_file
       undef yardoc_file, yardoc_file=
       def yardoc_file=(v) Thread.current[:__yard_yardoc_file__] = v end
+
       def yardoc_file
         Thread.current[:__yard_yardoc_file__] ||= DEFAULT_YARDOC_FILE
       end
@@ -248,7 +250,7 @@ module YARD
       # @param [Boolean] reload whether to load entire database
       # @return [Array<String>] all of the paths in the registry.
       def paths(reload = false)
-        thread_local_store.keys(reload).map {|k| k.to_s }
+        thread_local_store.keys(reload).map(&:to_s)
       end
 
       # Returns the object at a specific path.
@@ -257,7 +259,7 @@ module YARD
       # @return [CodeObjects::Base] the object at path
       # @return [nil] if no object is found
       def at(path) path ? thread_local_store[path] : nil end
-      alias_method :[], :at
+      alias [] at
 
       # The root namespace object.
       # @return [CodeObjects::RootObject] the root object in the namespace
@@ -347,6 +349,7 @@ module YARD
       attr_accessor :po_dir
       undef po_dir, po_dir=
       def po_dir=(dir) Thread.current[:__yard_po_dir__] = dir end
+
       def po_dir
         Thread.current[:__yard_po_dir__] ||= DEFAULT_PO_DIR
       end
@@ -375,9 +378,7 @@ module YARD
         [CodeObjects::NSEP, CodeObjects::CSEP, ''].each do |s|
           next if s.empty? && name =~ /^\w/
           path = name
-          if namespace != root
-            path = [namespace.path, name].join(s)
-          end
+          path = [namespace.path, name].join(s) if namespace != root
           found = at(path)
           return found if found && (type.nil? || found.type == type)
         end
@@ -391,7 +392,7 @@ module YARD
         yfile = spec.doc_dir(DEFAULT_YARDOC_FILE)
         if for_writing
           if File.writable?(path) ||
-              (!File.directory?(path) && File.writable?(File.dirname(path)))
+             (!File.directory?(path) && File.writable?(File.dirname(path)))
             return yfile
           end
         elsif !for_writing && File.exist?(yfile)
@@ -402,11 +403,8 @@ module YARD
       def old_global_yardoc_file(spec, for_writing = false)
         path = spec.full_gem_path
         yfile = File.join(path, DEFAULT_YARDOC_FILE)
-        if for_writing && File.writable?(path)
-          return yfile
-        elsif !for_writing && File.exist?(yfile)
-          return yfile
-        end
+        return yfile if for_writing && File.writable?(path)
+        return yfile if !for_writing && File.exist?(yfile)
       end
 
       def local_yardoc_file(spec, for_writing = false)

data/lib/yard/registry_resolver.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module YARD
   # Handles all logic for complex lexical and inherited object resolution.
   # Used by {Registry.resolve}, so there is no need to use this class
@@ -13,7 +14,8 @@ module YARD
     # @param registry [Registry] only set this if customizing the registry
     #   object
     def initialize(registry = Registry)
-      @registry = Registry
+      @registry = registry
+      @default_sep = nil
     end
 
     # Performs a lookup on a given path in the registry. Resolution will occur
@@ -61,14 +63,23 @@ module YARD
       orignamespace = namespace
 
       if path =~ /\A#{default_separator}/
-        path, namespace = $', @registry.root
+        path = $'
+        namespace = @registry.root
       end
 
       resolved = nil
+      lexical_lookup = 0
       while namespace && !resolved
         resolved = lookup_path_direct(namespace, path, type)
         resolved ||= lookup_path_inherited(namespace, path, type) if inheritance
+        break if resolved
         namespace = namespace.parent
+        lexical_lookup += 1
+      end
+
+      # method objects cannot be resolved through lexical lookup by more than 1 ns
+      if lexical_lookup > 1 && resolved.is_a?(CodeObjects::MethodObject)
+        resolved = nil
       end
 
       if proxy_fallback
@@ -82,14 +93,13 @@ module YARD
 
     # return [Boolean] if the obj's type matches the provided type.
     def validate(obj, type)
-      return !type || (obj && obj.type == type) ? obj : nil
+      !type || (obj && obj.type == type) ? obj : nil
     end
 
     # Performs a lexical lookup from a namespace for a path and a type hint.
     def lookup_path_direct(namespace, path, type)
-      if namespace.root? && result = validate(@registry.at(path), type)
-        return result
-      end
+      result = namespace.root? && validate(@registry.at(path), type)
+      return result if result
 
       if path =~ /\A(#{separators_match})/
         return validate(@registry.at(namespace.path + path), type)
@@ -105,10 +115,15 @@ module YARD
 
     # Performs a lookup through the inheritance chain on a path with a type hint.
     def lookup_path_inherited(namespace, path, type)
-      resolved, last_obj, scopes, last_sep, pos = nil, namespace, [], nil, 0
+      resolved = nil
+      last_obj = namespace
+      scopes = []
+      last_sep = nil
+      pos = 0
 
       if path =~ /\A(#{separators_match})/
-        last_sep, path = $1, $'
+        last_sep = $1
+        path = $'
       end
 
       path.scan(/(.+?)(#{separators_match}|$)/).each do |part, sep|
@@ -123,23 +138,26 @@ module YARD
         collect_namespaces(last_obj).each do |ns|
           next if ns.is_a?(CodeObjects::Proxy)
 
-          found, search_seps = nil, []
+          found = nil
+          search_seps = []
           scopes.each do |scope|
             search_seps += separators_for_type(scope)
           end
 
           if search_seps.empty?
-            if ns.type == :root
-              search_seps = [""]
-            elsif last_sep.nil?
-              search_seps = separators
-            else
-              search_seps = [@default_sep]
-            end
+            search_seps =
+              if ns.type == :root
+                [""]
+              elsif last_sep.nil?
+                separators
+              else
+                [@default_sep]
+              end
           end
 
           ([last_sep] | search_seps).compact.each do |search_sep|
-            break if found = @registry.at(ns.path + search_sep.to_s + part) 
+            found = @registry.at(ns.path + search_sep.to_s + part)
+            break if found
           end
 
           break cur_obj = found if found
@@ -160,9 +178,7 @@ module YARD
 
       nss = object.inheritance_tree(true)
       if object.respond_to?(:superclass)
-        if object.superclass != P('BasicObject')
-          nss |= [P('Object')]
-        end
+        nss |= [P('Object')] if object.superclass != P('BasicObject')
         nss |= [P('BasicObject')]
       end