1 files changed, 90 insertions, 31 deletions

diff --git a/lib/rdoc/ri/paths.rb b/lib/rdoc/ri/paths.rb
index a3c65bf928..d7ea285eaa 100644
--- a/lib/rdoc/ri/paths.rb
+++ b/lib/rdoc/ri/paths.rb
@@ -1,7 +1,8 @@
 require 'rdoc/ri'
 
 ##
-# The directories where ri data lives.
+# The directories where ri data lives.  Paths can be enumerated via ::each, or
+# queried individually via ::system_dir, ::site_dir, ::home_dir and ::gem_dir.
 
 module RDoc::RI::Paths
 
@@ -10,15 +11,12 @@ module RDoc::RI::Paths
 
   version = RbConfig::CONFIG['ruby_version']
 
-  base    = if RbConfig::CONFIG.key? 'ridir' then
+  BASE    = if RbConfig::CONFIG.key? 'ridir' then
               File.join RbConfig::CONFIG['ridir'], version
             else
               File.join RbConfig::CONFIG['datadir'], 'ri', version
             end
 
-  SYSDIR  = File.join base, "system"
-  SITEDIR = File.join base, "site"
-
   homedir = begin
               File.expand_path('~')
             rescue ArgumentError
@@ -32,8 +30,6 @@ module RDoc::RI::Paths
             end
   #:startdoc:
 
-  @gemdirs = nil
-
   ##
   # Iterates over each selected path yielding the directory and type.
   #
@@ -47,16 +43,19 @@ module RDoc::RI::Paths
   # :extra:: ri data directory from the command line.  Yielded for each
   #          entry in +extra_dirs+
 
-  def self.each system, site, home, gems, *extra_dirs # :yields: directory, type
+  def self.each system = true, site = true, home = true, gems = :latest, *extra_dirs # :yields: directory, type
+    return enum_for __method__, system, site, home, gems, *extra_dirs unless
+      block_given?
+
     extra_dirs.each do |dir|
       yield dir, :extra
     end
 
-    yield SYSDIR,  :system if system
-    yield SITEDIR, :site   if site
-    yield HOMEDIR, :home   if home and HOMEDIR
+    yield system_dir,  :system if system
+    yield site_dir,    :site   if site
+    yield home_dir,    :home   if home and HOMEDIR
 
-    gemdirs.each do |dir|
+    gemdirs(gems).each do |dir|
       yield dir, :gem
     end if gems
 
@@ -64,36 +63,72 @@ module RDoc::RI::Paths
   end
 
   ##
-  # The latest installed gems' ri directories
+  # The ri directory for the gem with +gem_name+.
 
-  def self.gemdirs
-    return @gemdirs if @gemdirs
+  def self.gem_dir name, version
+    req = Gem::Requirement.new "= #{version}"
 
-    require 'rubygems' unless defined?(Gem)
+    spec = Gem::Specification.find_by_name name, req
 
-    # HACK dup'd from Gem.latest_partials and friends
-    all_paths = []
+    File.join spec.doc_dir, 'ri'
+  end
 
-    all_paths = Gem.path.map do |dir|
-      Dir[File.join(dir, 'doc', '*', 'ri')]
-    end.flatten
+  ##
+  # The latest installed gems' ri directories.  +filter+ can be :all or
+  # :latest.
+  #
+  # A +filter+ :all includes all versions of gems and includes gems without
+  # ri documentation.
+
+  def self.gemdirs filter = :latest
+    require 'rubygems' unless defined?(Gem)
 
     ri_paths = {}
 
-    all_paths.each do |dir|
-      base = File.basename File.dirname(dir)
-      if base =~ /(.*)-((\d+\.)*\d+)/ then
-        name, version = $1, $2
-        ver = Gem::Version.new version
-        if ri_paths[name].nil? or ver > ri_paths[name][0] then
-          ri_paths[name] = [ver, dir]
+    all = Gem::Specification.map do |spec|
+      [File.join(spec.doc_dir, 'ri'), spec.name, spec.version]
+    end
+
+    if filter == :all then
+      gemdirs = []
+
+      all.group_by do |_, name, _|
+        name
+      end.sort_by do |group, _|
+        group
+      end.map do |group, items|
+        items.sort_by do |_, _, version|
+          version
+        end.reverse_each do |dir,|
+          gemdirs << dir
         end
       end
+
+      return gemdirs
+    end
+
+    all.each do |dir, name, ver|
+      next unless File.exist? dir
+
+      if ri_paths[name].nil? or ver > ri_paths[name].first then
+        ri_paths[name] = [ver, name, dir]
+      end
     end
 
-    @gemdirs = ri_paths.map { |k,v| v.last }.sort
+    ri_paths.sort_by { |_, (_, name, _)| name }.map { |k, v| v.last }
   rescue LoadError
-    @gemdirs = []
+    []
+  end
+
+  ##
+  # The location of the rdoc data in the user's home directory.
+  #
+  # Like ::system, ri data in the user's home directory is rare and predates
+  # libraries distributed via RubyGems.  ri data is rarely generated into this
+  # directory.
+
+  def self.home_dir
+    HOMEDIR
   end
 
   ##
@@ -102,7 +137,7 @@ module RDoc::RI::Paths
   #
   # See also ::each
 
-  def self.path(system, site, home, gems, *extra_dirs)
+  def self.path(system = true, site = true, home = true, gems = :latest, *extra_dirs)
     path = raw_path system, site, home, gems, *extra_dirs
 
     path.select { |directory| File.directory? directory }
@@ -124,5 +159,29 @@ module RDoc::RI::Paths
     path.compact
   end
 
+  ##
+  # The location of ri data installed into the site dir.
+  #
+  # Historically this was available for documentation installed by ruby
+  # libraries predating RubyGems.  It is unlikely to contain any content for
+  # modern ruby installations.
+
+  def self.site_dir
+    File.join BASE, 'site'
+  end
+
+  ##
+  # The location of the built-in ri data.
+  #
+  # This data is built automatically when `make` is run when ruby is
+  # installed.  If you did not install ruby by hand you may need to install
+  # the documentation yourself.  Please consult the documentation for your
+  # package manager or ruby installer for details.  You can also use the
+  # rdoc-data gem to install system ri data for common versions of ruby.
+
+  def self.system_dir
+    File.join BASE, 'system'
+  end
+
 end