yard 0.5.8 → 0.6.0

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

@@ -3,6 +3,7 @@ module YARD
     module Ruby
       module Legacy
         # Legacy Ruby parser
+        # @since 0.5.6
         class RubyParser < Parser::Base
           def initialize(source, filename)
             @source = source

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

@@ -2,7 +2,7 @@ module YARD
   module Parser::Ruby::Legacy
     class Statement 
       attr_reader :tokens, :comments, :block
-      attr_accessor :comments_range
+      attr_accessor :comments_range, :group
 
       def initialize(tokens, block = nil, comments = nil)
         @tokens = tokens
@@ -11,23 +11,26 @@ module YARD
       end
       
       def first_line
-        to_s(false)
+        to_s.split(/\n/)[0]
       end
       
       def to_s(include_block = true)
         tokens.map do |token|
-          RubyToken::TkBlockContents === token ? block.to_s : token.text
+          RubyToken::TkBlockContents === token ? (include_block ? block.to_s : '') : token.text
         end.join
       end
       alias source to_s
       
       def inspect
         l = line - 1
-        to_s.split(/\n/).map do |text|
+        to_s(false).split(/\n/).map do |text|
           "\t#{l += 1}:  #{text}"
         end.join("\n")
       end
-      alias show inspect
+      
+      def show
+        "\t #{line}: #{first_line}"
+      end
       
       # @return [Fixnum] the first line of Ruby source
       def line
@@ -35,6 +38,7 @@ module YARD
       end
       
       # @return [Range<Fixnum>] the first to last lines of Ruby source
+      # @since 0.5.4
       def line_range
         tokens.first.line_no..tokens.last.line_no
       end

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

@@ -8,11 +8,11 @@ module YARD
       OPEN_BLOCK_TOKENS = [TkCLASS, TkDEF, TkMODULE, TkUNTIL,
                            TkIF, TkELSIF, TkUNLESS, TkWHILE, TkFOR, TkCASE]
 
-      ##
       # Creates a new statement list
       #
       # @param [TokenList, String] content the tokens to create the list from
       def initialize(content)
+        @group = nil
         if content.is_a? TokenList
           @tokens = content.dup
         elsif content.is_a? String
@@ -30,7 +30,6 @@ module YARD
         while stmt = next_statement do self << stmt end
       end
 
-      ##
       # Returns the next statement in the token stream
       #
       # @return [Statement] the next statement
@@ -62,6 +61,7 @@ module YARD
           sanitize_block
           @statement.pop if [TkNL, TkSPACE, TkSEMICOLON].include?(@statement.last.class)
           stmt = Statement.new(@statement, @block, @comments)
+          stmt.group = @group
           if @comments && @comments_line
             stmt.comments_range = (@comments_line..(@comments_line + @comments.size - 1))
           end
@@ -101,8 +101,24 @@ module YARD
           end
         end
       end
+      
+      def preprocess_token(tk)
+        if tk.is_a?(TkCOMMENT)
+          case tk.text
+          when /\A# @group\s+(.+)\s*\Z/
+            @group = $1
+            true
+          when /\A# @endgroup\s*\Z/
+            @group = nil
+            true
+          else
+            false
+          end
+        else
+          false
+        end
+      end
 
-      ##
       # Processes a single token
       #
       # @param [RubyToken::Token] tk the token to process
@@ -110,6 +126,7 @@ module YARD
         # p tk.class, tk.text, @state, @level, @current_block, "<br/>"
         case @state
         when :first_statement
+          return if preprocess_token(tk)
           return if process_initial_comment(tk)
           return if @statement.empty? && [TkSPACE, TkNL, TkCOMMENT].include?(tk.class)
           @comments_last_line = nil
@@ -152,7 +169,6 @@ module YARD
         end
       end
 
-      ##
       # Processes a token in a block
       #
       # @param [RubyToken::Token] tk the token to process
@@ -171,7 +187,6 @@ module YARD
         end
       end
 
-      ##
       # Processes a comment token that comes before a statement
       #
       # @param [RubyToken::Token] tk the token to process
@@ -204,7 +219,6 @@ module YARD
         true
       end
 
-      ##
       # Processes a simple block-opening token;
       # that is, a block opener such as +begin+ or +do+
       # that isn't followed by an expression
@@ -230,7 +244,6 @@ module YARD
         true
       end
 
-      ##
       # Processes a complex block-opening token;
       # that is, a block opener such as +while+ or +for+
       # that is followed by an expression
@@ -246,7 +259,6 @@ module YARD
         true
       end
 
-      ##
       # Processes a token that closes a statement
       #
       # @param [RubyToken::Token] tk the token to process
@@ -300,7 +312,6 @@ module YARD
         end
       end
 
-      ##
       # Handles the balancing of parentheses and blocks
       #
       # @param [RubyToken::Token] tk the token to process
@@ -318,7 +329,6 @@ module YARD
         @level == 0
       end
 
-      ##
       # Adds a token to the current statement,
       # unless it's a newline, semicolon, or comment
       #
@@ -328,7 +338,6 @@ module YARD
         @statement << tk unless @level == 0 && [TkCOMMENT].include?(tk.class)
       end
 
-      ##
       # Returns the next token in the stream that's not a space
       #
       # @return [RubyToken::Token] the next non-space token

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

@@ -15,6 +15,7 @@ module YARD
       end
       
       # Internal parser class
+      # @since 0.5.6
       class RipperParser < Ripper
         attr_reader :ast, :charno, :comments, :file, :tokens
         alias root ast
@@ -30,6 +31,7 @@ module YARD
           @ns_charno = 0
           @list = []
           @charno = 0
+          @groups = []
         end
 
         def parse
@@ -346,7 +348,15 @@ module YARD
 
         def on_comment(comment)
           visit_ns_token(:comment, comment)
-          
+          case comment
+          when /\A# @group\s+(.+)\s*\Z/
+            @groups.unshift [lineno, $1]
+            return
+          when /\A# @endgroup\s*\Z/
+            @groups.unshift [lineno, nil]
+            return
+          end
+
           comment = comment.gsub(/^\#{1,2}\s{0,1}/, '').chomp
           append_comment = @comments[lineno - 1]
           
@@ -391,6 +401,13 @@ module YARD
                 break
               end
             end
+            if node.type == :def || node.type == :defs || node.call?
+              @groups.each do |group|
+                if group.first < node.line
+                  break node.group = group.last
+                end
+              end
+            end
           end
         end
         

data/lib/yard/parser/source_parser.rb

@@ -103,6 +103,7 @@ module YARD
         
         # @return [Hash{Symbol=>Object}] a list of registered parser types
         # @private
+        # @since 0.5.6
         attr_reader :parser_types
         undef parser_types
         def parser_types; @@parser_types ||= {} end
@@ -110,6 +111,7 @@ module YARD
         
         # @return [Hash] a list of registered parser type extensions
         # @private
+        # @since 0.5.6
         attr_reader :parser_type_extensions
         undef parser_type_extensions
         def parser_type_extensions; @@parser_type_extensions ||= {} end
@@ -119,6 +121,7 @@ module YARD
         # type is found, the default Ruby type is returned.
         # 
         # @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|
             [exts].flatten.any? {|ext| ext === extension }
@@ -230,9 +233,10 @@ module YARD
       private
       
       # Searches for encoding line and forces encoding
+      # @since 0.5.3
       def convert_encoding(content)
         return content if RUBY18
-        if content =~ /\A\s*#.*coding:\s*(\S+)\s*$/
+        if content =~ /\A\s*#.*coding[:=]\s*(\S+)\s*$/
           content.force_encoding($1)
         else
           content
@@ -262,6 +266,7 @@ module YARD
         parser_type == :ruby18 && type == :ruby ? :ruby18 : type
       end
       
+      # @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

data/lib/yard/registry.rb

@@ -1,4 +1,3 @@
-require 'singleton'
 require 'fileutils'
 require 'digest/sha1'
 
@@ -7,34 +6,23 @@ module YARD
   # during parsing. The storage is a key value store with the object's path
   # (see {CodeObjects::Base#path}) as the key and the object itself as the value.
   # Object paths must be unique to be stored in the Registry. All lookups for 
-  # objects are done on the singleton Registry instance using the {Registry#at} 
-  # or {Registry#resolve} methods.
+  # objects are done on the singleton Registry instance using the {Registry.at} 
+  # or {Registry.resolve} methods.
   # 
   # The registry is saved to a "yardoc" file, which can be loaded back to 
   # perform any lookups.
   # 
   # This class is a singleton class. Any method called on the class will be
   # delegated to the instance.
-  class Registry 
+  module Registry
     DEFAULT_YARDOC_FILE = ".yardoc"
     LOCAL_YARDOC_INDEX = File.expand_path('~/.yard/gem_index')
-    
-    include Singleton
-  
-    @objects = {}
+    @yardoc_file = DEFAULT_YARDOC_FILE
+
+    extend Enumerable
 
     class << self
-      # Holds the objects cache. This attribute should never be accessed
-      # directly.
-      # @return [Array<CodeObjects::Base>] the objects cache
-      attr_reader :objects
-      
-      # Clears the registry and cache
-      # @return [void] 
-      def clear
-        instance.clear 
-        objects.clear
-      end
+      # @group Getting .yardoc File Locations
 
       # Returns the .yardoc file associated with a gem.
       # 
@@ -51,12 +39,12 @@ module YARD
         spec = Gem.source_index.find_name(gem, ver_require)
         return if spec.empty?
         spec = spec.first
-        
+      
         if gem =~ /^yard-doc-/
           path = File.join(spec.full_gem_path, DEFAULT_YARDOC_FILE)
           return File.exist?(path) && !for_writing ? path : nil
         end
-        
+      
         if for_writing
           global_yardoc_file(spec, for_writing) ||
             local_yardoc_file(spec, for_writing)
@@ -65,292 +53,310 @@ module YARD
             global_yardoc_file(spec, for_writing)
         end
       end
-      
-      private
-      
-      def 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
-      end
-      
-      def local_yardoc_file(spec, for_writing = false)
-        path = Registry::LOCAL_YARDOC_INDEX
-        FileUtils.mkdir_p(path) if for_writing
-        path = File.join(path, "#{spec.full_name}.yardoc")
-        if for_writing
-          path
+    
+      # Gets/sets the yardoc filename
+      # @return [String] the yardoc filename
+      # @see DEFAULT_YARDOC_FILE
+      attr_accessor :yardoc_file
+    
+      # @group Loading Data from Disk
+    
+      # Loads the registry and/or parses a list of files
+      # 
+      # @example Loads the yardoc file or parses files 'a', 'b' and 'c' (but not both)
+      #   Registry.load(['a', 'b', 'c'])
+      # @example Reparses files 'a' and 'b' regardless of whether yardoc file exists
+      #   Registry.load(['a', 'b'], true)
+      # @param [String, Array] files if +files+ is an Array, it should represent
+      #   a list of files that YARD should parse into the registry. If reload is
+      #   set to false and the yardoc file already exists, these files are skipped.
+      #   If files is a String, it should represent the yardoc file to load
+      #   into the registry.
+      # @param [Boolean] reparse if reparse is false and a yardoc file already
+      #   exists, any files passed in will be ignored.
+      # @return [Registry] the registry object (for chaining)
+      # @raise [ArgumentError] if files is not a String or Array
+      def load(files = [], reparse = false)
+        if files.is_a?(Array)
+          if File.exists?(yardoc_file) && !reparse
+            load_yardoc
+          else
+            size = @store.keys.size
+            YARD.parse(files)
+            save if @store.keys.size > size
+          end
+        elsif files.is_a?(String)
+          load_yardoc(files)
         else
-          File.exist?(path) ? path : nil
+          raise ArgumentError, "Must take a list of files to parse or the .yardoc file to load."
         end
+        self
       end
-    end
-
-    # Gets/sets the yardoc filename
-    # @return [String] the yardoc filename
-    # @see DEFAULT_YARDOC_FILE
-    attr_accessor :yardoc_file
     
-    # The assumed types of a list of paths
-    # @return [{String => Symbol}] a set of unresolved paths and their assumed type
-    def proxy_types
-      @store.proxy_types
-    end
+      # Loads a yardoc file directly
+      # 
+      # @param [String] file the yardoc file to load.
+      # @return [Registry] the registry object (for chaining)
+      def load_yardoc(file = yardoc_file)
+        clear
+        @store.load(file)
+        self
+      end
     
-    # Loads the registry and/or parses a list of files
-    # 
-    # @example Loads the yardoc file or parses files 'a', 'b' and 'c' (but not both)
-    #   Registry.load(['a', 'b', 'c'])
-    # @example Reparses files 'a' and 'b' regardless if yardoc file exists
-    #   Registry.load(['a', 'b'], true)
-    # @param [String, Array] files if +files+ is an Array, it should represent
-    #   a list of files that YARD should parse into the registry. If reload is
-    #   set to false and the yardoc file already exists, these files are skipped.
-    #   If files is a String, it should represent the yardoc file to load
-    #   into the registry.
-    # @param [Boolean] reload if reload is false and a yardoc file already
-    #   exists, any files passed in will be ignored.
-    # @return [Boolean] true if the registry was successfully loaded 
-    # @raise [ArgumentError] if files is not a String or Array
-    def load(files = [], reload = false)
-      if files.is_a?(Array)
-        if File.exists?(yardoc_file) && !reload
-          load_yardoc
-        else
-          size = @store.keys.size
-          YARD.parse(files)
-          save if @store.keys.size > size
-        end
-        true
-      elsif files.is_a?(String)
-        load_yardoc(files)
-        true
-      else
-        raise ArgumentError, "Must take a list of files to parse or the .yardoc file to load."
+      # Loads a yardoc file and forces all objects cached on disk into
+      # memory. Equivalent to calling {load_yardoc} followed by {load_all}
+      # 
+      # @param [String] file the yardoc file to load
+      # @return [Registry] the registry object (for chaining)
+      # @see #load_yardoc
+      # @see #load_all
+      # @since 0.5.1
+      def load!(file = yardoc_file)
+        clear
+        @store.load!(file)
+        self
       end
-    end
     
-    # Loads a yardoc file directly
-    # 
-    # @param [String] file the yardoc file to load.
-    # @return [void] 
-    def load_yardoc(file = yardoc_file)
-      clear
-      @store.load(file)
-    end
+      # Forces all objects cached on disk into memory
+      # 
+      # @example Loads all objects from disk
+      #   Registry.load
+      #   Registry.all.count #=> 0
+      #   Registry.load_all
+      #   Registry.all.count #=> 17
+      # @return [Registry] the registry object (for chaining)
+      # @since 0.5.1
+      def load_all
+        @store.load_all
+        self
+      end
     
-    # Loads a yardoc file and forces all objects cached on disk into
-    # memory. Equivalent to calling {#load_yardoc} followed by {#load_all}
-    # 
-    # @param [String] file the yardoc file to load
-    # @return [void]
-    # @see #load_yardoc
-    # @see #load_all
-    def load!(file = yardoc_file)
-      clear
-      @store.load!(file)
-    end
+      # @group Saving and Deleting Data from Disk
+
+      # Saves the registry to +file+
+      # 
+      # @param [String] file the yardoc file to save to
+      # @return [Boolean] true if the file was saved
+      def save(merge = false, file = yardoc_file)
+        @store.save(merge, file)
+      end
     
-    # Forces all objects cached on disk into memory
-    # 
-    # @example Loads all objects from disk
-    #   Registry.load
-    #   Registry.all.count #=> 0
-    #   Registry.load_all
-    #   Registry.all.count #=> 17
-    # @return [void]
-    def load_all
-      @store.load_all
-    end
+      # Deletes the yardoc file from disk
+      # @return [void]
+      def delete_from_disk
+        @store.destroy
+      end
+    
+      # @group Adding and Deleting Objects from the Registry
 
-    # Saves the registry to +file+
-    # 
-    # @param [String] file the yardoc file to save to
-    # @return [Boolean] true if the file was saved
-    def save(merge = false, file = yardoc_file)
-      @store.save(merge, file)
-    end
+      # Registers a new object with the registry
+      # 
+      # @param [CodeObjects::Base] object the object to register
+      # @return [CodeObjects::Base] the registered object
+      def register(object)
+        return if object.is_a?(CodeObjects::Proxy)
+        @store[object.path] = object
+      end
     
-    # @return [Hash{String => String}] a set of checksums for files
-    def checksums
-      @store.checksums
-    end
+      # Deletes an object from the registry
+      # @param [CodeObjects::Base] object the object to remove
+      # @return [void] 
+      def delete(object) 
+        @store.delete(object.path)
+      end
+
+      # Clears the registry
+      # @return [void] 
+      def clear
+        @store = RegistryStore.new
+      end
+
+      # @group Accessing Objects in the Registry
+     
+      # Iterates over {all} with no arguments
+      def each(&block)
+        all.each(&block)
+      end
     
-    # @param [String] data data to checksum
-    # @return [String] the SHA1 checksum for data
-    def checksum_for(data)
-      Digest::SHA1.hexdigest(data)
-    end
+      # Returns all objects in the registry that match one of the types provided
+      # in the +types+ list (if +types+ is provided).
+      # 
+      # @example Returns all objects
+      #   Registry.all
+      # @example Returns all classes and modules
+      #   Registry.all(:class, :module)
+      # @param [Array<Symbol>] types an optional list of types to narrow the
+      #   objects down by. Equivalent to performing a select: 
+      #     +Registry.all.select {|o| types.include(o.type) }+
+      # @return [Array<CodeObjects::Base>] the list of objects found
+      # @see CodeObjects::Base#type
+      def all(*types)
+        @store.values.select do |obj| 
+          if types.empty?
+            obj != root
+          else
+            obj != root &&
+              types.any? do |type| 
+                type.is_a?(Symbol) ? obj.type == type : obj.is_a?(type)
+              end
+          end
+        end + (types.include?(:root) ? [root] : [])
+      end
     
-    # Deletes the yardoc file from disk
-    # @return [void]
-    def delete_from_disk
-      @store.destroy
-    end
+      # Returns the paths of all of the objects in the registry.
+      # @param [Boolean] reload whether to load entire database
+      # @return [Array<String>] all of the paths in the registry.
+      def paths(reload = false)
+        @store.keys(reload).map {|k| k.to_s }
+      end
+    
+      # Returns the object at a specific path.
+      # @param [String, :root] path the pathname to look for. If +path+ is +root+,
+      #   returns the {root} object.
+      # @return [CodeObjects::Base] the object at path
+      # @return [nil] if no object is found
+      def at(path) @store[path] end
+      alias_method :[], :at
+    
+      # The root namespace object.
+      # @return [CodeObjects::RootObject] the root object in the namespace
+      def root; @store[:root] end
+    
+      # Attempts to find an object by name starting at +namespace+, performing
+      # a lookup similar to Ruby's method of resolving a constant in a namespace.
+      # 
+      # @example Looks for instance method #reverse starting from A::B::C
+      #   Registry.resolve(P("A::B::C"), "#reverse")
+      # @example Looks for a constant in the root namespace
+      #   Registry.resolve(nil, 'CONSTANT')
+      # @example Looks for a class method respecting the inheritance tree
+      #   Registry.resolve(myclass, 'mymethod', true)
+      # @example Looks for a constant but returns a proxy if not found
+      #   Registry.resolve(P('A::B::C'), 'D', false, true) # => #<yardoc proxy A::B::C::D>
+      # @example Looks for a complex path from a namespace
+      #   Registry.resolve(P('A::B'), 'B::D') # => #<yardoc class A::B::D>
+      # @param [CodeObjects::NamespaceObject, nil] namespace the starting namespace
+      #   (module or class). If +nil+ or +:root+, starts from the {root} object.
+      # @param [String, Symbol] name the name (or complex path) to look for from
+      #   +namespace+.
+      # @param [Boolean] inheritance Follows inheritance chain (mixins, superclass)
+      #   when performing name resolution if set to +true+.
+      # @param [Boolean] proxy_fallback If +true+, returns a proxy representing
+      #   the unresolved path (namespace + name) if no object is found.
+      # @return [CodeObjects::Base] the object if it is found
+      # @return [CodeObjects::Proxy] a Proxy representing the object if 
+      #   +proxy_fallback+ is +true+.
+      # @return [nil] if +proxy_fallback+ is +false+ and no object was found.
+      # @see P
+      def resolve(namespace, name, inheritance = false, proxy_fallback = false)
+        if namespace.is_a?(CodeObjects::Proxy)
+          return proxy_fallback ? CodeObjects::Proxy.new(namespace, name) : nil
+        end
+      
+        if namespace == :root || !namespace
+          namespace = root
+        else
+          namespace = namespace.parent until namespace.is_a?(CodeObjects::NamespaceObject)
+        end
+        orignamespace = namespace
 
-    # Returns all objects in the registry that match one of the types provided
-    # in the +types+ list (if +types+ is provided).
-    # 
-    # @example Returns all objects
-    #   Registry.all
-    # @example Returns all classes and modules
-    #   Registry.all(:class, :module)
-    # @param [Array<Symbol>] types an optional list of types to narrow the
-    #   objects down by. Equivalent to performing a select: 
-    #     +Registry.all.select {|o| types.include(o.type) }+
-    # @return [Array<CodeObjects::Base>] the list of objects found
-    # @see CodeObjects::Base#type
-    def all(*types)
-      @store.values.select do |obj| 
-        if types.empty?
-          obj != root
+        name = name.to_s
+        if name =~ /^#{CodeObjects::NSEPQ}/
+          [name, name[2..-1]].each do |n|
+            return at(n) if at(n)
+          end
         else
-          obj != root &&
-            types.any? do |type| 
-              type.is_a?(Symbol) ? obj.type == type : obj.is_a?(type)
+          while namespace
+            if namespace.is_a?(CodeObjects::NamespaceObject)
+              nss = inheritance ? namespace.inheritance_tree(true) : [namespace]
+              nss.each do |ns|
+                next if ns.is_a?(CodeObjects::Proxy)
+                found = partial_resolve(ns, name)
+                return found if found
+              end
             end
+            namespace = namespace.parent
+          end
         end
-      end + (types.include?(:root) ? [root] : [])
-    end
-    
-    # Returns the paths of all of the objects in the registry.
-    # @param [Boolean] reload whether to load entire database
-    # @return [Array<String>] all of the paths in the registry.
-    def paths(reload = false)
-      @store.keys(reload).map {|k| k.to_s }
-    end
+        proxy_fallback ? CodeObjects::Proxy.new(orignamespace, name) : nil
+      end
+
+      # @group Managing Source File Checksums
     
-    # Returns the object at a specific path.
-    # @param [String, :root] path the pathname to look for. If +path+ is +root+,
-    #   returns the {#root} object.
-    # @return [CodeObjects::Base] the object at path
-    # @return [nil] if no object is found
-    def at(path) @store[path] end
-    alias_method :[], :at
+      # @return [Hash{String => String}] a set of checksums for files
+      def checksums
+        @store.checksums
+      end
     
-    # The root namespace object.
-    # @return [CodeObjects::RootObject] the root object in the namespace
-    def root; @store[:root] end
+      # @param [String] data data to checksum
+      # @return [String] the SHA1 checksum for data
+      def checksum_for(data)
+        Digest::SHA1.hexdigest(data)
+      end
     
-    # Deletes an object from the registry
-    # @param [CodeObjects::Base] object the object to remove
-    # @return [void] 
-    def delete(object) 
-      @store.delete(object.path)
-      self.class.objects.delete(object.path)
-    end
-
-    # Clears the registry
-    # @return [void] 
-    def clear
-      @store = RegistryStore.new
-    end
-
-    # Creates the Registry
-    # @return [Registry]
-    def initialize
-      @yardoc_file = DEFAULT_YARDOC_FILE
-      clear
-    end
-  
-    # Registers a new object with the registry
-    # 
-    # @param [CodeObjects::Base] object the object to register
-    # @return [CodeObjects::Base] the registered object
-    def register(object)
-      self.class.objects[object.path] = object
-      return if object.is_a?(CodeObjects::Proxy)
-      @store[object.path] = object
-    end
+      # @group Managing Internal State (Testing Only)
 
-    # Attempts to find an object by name starting at +namespace+, performing
-    # a lookup similar to Ruby's method of resolving a constant in a namespace.
-    # 
-    # @example Looks for instance method #reverse starting from A::B::C
-    #   Registry.resolve(P("A::B::C"), "#reverse")
-    # @example Looks for a constant in the root namespace
-    #   Registry.resolve(nil, 'CONSTANT')
-    # @example Looks for a class method respecting the inheritance tree
-    #   Registry.resolve(myclass, 'mymethod', true)
-    # @example Looks for a constant but returns a proxy if not found
-    #   Registry.resolve(P('A::B::C'), 'D', false, true) # => #<yardoc proxy A::B::C::D>
-    # @example Looks for a complex path from a namespace
-    #   Registry.resolve(P('A::B'), 'B::D') # => #<yardoc class A::B::D>
-    # @param [CodeObjects::NamespaceObject, nil] namespace the starting namespace
-    #   (module or class). If +nil+ or +:root+, starts from the {#root} object.
-    # @param [String, Symbol] name the name (or complex path) to look for from
-    #   +namespace+.
-    # @param [Boolean] inheritance Follows inheritance chain (mixins, superclass)
-    #   when performing name resolution if set to +true+.
-    # @param [Boolean] proxy_fallback If +true+, returns a proxy representing
-    #   the unresolved path (namespace + name) if no object is found.
-    # @return [CodeObjects::Base] the object if it is found
-    # @return [CodeObjects::Proxy] a Proxy representing the object if 
-    #   +proxy_fallback+ is +true+.
-    # @return [nil] if +proxy_fallback+ is +false+ and no object was found.
-    # @see P
-    def resolve(namespace, name, inheritance = false, proxy_fallback = false)
-      if namespace.is_a?(CodeObjects::Proxy)
-        return proxy_fallback ? CodeObjects::Proxy.new(namespace, name) : nil
+      # The assumed types of a list of paths. This method is used by CodeObjects::Base
+      # @return [{String => Symbol}] a set of unresolved paths and their assumed type
+      # @private
+      def proxy_types
+        @store.proxy_types
       end
       
-      if namespace == :root || !namespace
-        namespace = root
-      else
-        namespace = namespace.parent until namespace.is_a?(CodeObjects::NamespaceObject)
-      end
-      orignamespace = namespace
+      # @group Legacy Methods
+      
+      # The registry singleton instance.
+      # 
+      # @deprecated use Registry.methodname directly.
+      # @return [Registry] returns the registry instance
+      def instance; self end
+    
+      private
+    
+      # @group Accessing Objects in the Registry
 
-      name = name.to_s
-      if name =~ /^#{CodeObjects::NSEPQ}/
-        [name, name[2..-1]].each do |n|
-          return at(n) if at(n)
-        end
-      else
-        while namespace
-          if namespace.is_a?(CodeObjects::NamespaceObject)
-            nss = inheritance ? namespace.inheritance_tree(true) : [namespace]
-            nss.each do |ns|
-              next if ns.is_a?(CodeObjects::Proxy)
-              found = partial_resolve(ns, name)
-              return found if found
-            end
+      # Attempts to resolve a name in a namespace
+      # 
+      # @param [CodeObjects::NamespaceObject] namespace the starting namespace
+      # @param [String] name the name to look for
+      def partial_resolve(namespace, name)
+        return at(name) || at('#' + name) if namespace.root?
+        [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
-          namespace = namespace.parent
+          found = at(path)
+          return found if found
         end
+        nil
       end
-      proxy_fallback ? CodeObjects::Proxy.new(orignamespace, name) : nil
-    end
     
-    # Define all instance methods as singleton methods on instance
-    (public_instance_methods(false) - public_methods(false)).each do |meth|
-      module_eval(<<-eof, __FILE__, __LINE__ + 1) 
-        def self.#{meth}(*args, &block) instance.send(:#{meth}, *args, &block) end
-      eof
-    end
-
-    private
-
-    # Attempts to resolve a name in a namespace
-    # 
-    # @param [CodeObjects::NamespaceObject] namespace the starting namespace
-    # @param [String] name the name to look for
-    def partial_resolve(namespace, name)
-      return at(name) || at('#' + name) if namespace.root?
-      [CodeObjects::NSEP, CodeObjects::CSEP, ''].each do |s|
-        next if s.empty? && name =~ /^\w/
-        path = name
-        if namespace != root
-          path = [namespace.path, name].join(s)
+      # @group Retrieving yardoc File Locations
+    
+      def 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
+      end
+    
+      def local_yardoc_file(spec, for_writing = false)
+        path = Registry::LOCAL_YARDOC_INDEX
+        FileUtils.mkdir_p(path) if for_writing
+        path = File.join(path, "#{spec.full_name}.yardoc")
+        if for_writing
+          path
+        else
+          File.exist?(path) ? path : nil
         end
-        found = at(path)
-        return found if found
       end
-      nil
     end
+    
+    clear
   end
-end
+end