rdoc 5.1.0 → 6.3.1

data/lib/rdoc/ri/driver.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 require 'abbrev'
 require 'optparse'
 
@@ -17,7 +17,7 @@ require 'rdoc'
 ##
 # For RubyGems backwards compatibility
 
-require 'rdoc/ri/formatter'
+require_relative 'formatter'
 
 ##
 # The RI driver implements the command-line ri tool.
@@ -47,13 +47,24 @@ class RDoc::RI::Driver
 
   class NotFoundError < Error
 
+    def initialize(klass, suggestions = nil) # :nodoc:
+      @klass = klass
+      @suggestions = suggestions
+    end
+
     ##
     # Name that wasn't found
 
-    alias name message
+    def name
+      @klass
+    end
 
     def message # :nodoc:
-      "Nothing known about #{super}"
+      str = "Nothing known about #{@klass}"
+      if @suggestions and !@suggestions.empty?
+        str += "\nDid you mean?  #{@suggestions.join("\n               ")}"
+      end
+      str
     end
   end
 
@@ -80,7 +91,6 @@ class RDoc::RI::Driver
     options[:interactive] = false
     options[:profile]     = false
     options[:show_all]    = false
-    options[:use_cache]   = true
     options[:use_stdout]  = !$stdout.tty?
     options[:width]       = 72
 
@@ -100,7 +110,7 @@ class RDoc::RI::Driver
   def self.dump data_path
     require 'pp'
 
-    open data_path, 'rb' do |io|
+    File.open data_path, 'rb' do |io|
       pp Marshal.load(io.read)
     end
   end
@@ -122,7 +132,7 @@ class RDoc::RI::Driver
       opt.summary_indent = ' ' * 4
 
       opt.banner = <<-EOT
-Usage: #{opt.program_name} [options] [names...]
+Usage: #{opt.program_name} [options] [name ...]
 
 Where name can be:
 
@@ -132,8 +142,8 @@ Where name can be:
 
   gem_name: | gem_name:README | gem_name:History
 
-All class names may be abbreviated to their minimum unambiguous form. If a name
-is ambiguous, all valid options will be listed.
+All class names may be abbreviated to their minimum unambiguous form.
+If a name is ambiguous, all valid options will be listed.
 
 A '.' matches either class or instance methods, while #method
 matches only instance and ::method matches only class methods.
@@ -151,23 +161,23 @@ For example:
     #{opt.program_name} zip
     #{opt.program_name} rdoc:README
 
-Note that shell quoting or escaping may be required for method names containing
-punctuation:
+Note that shell quoting or escaping may be required for method names
+containing punctuation:
 
     #{opt.program_name} 'Array.[]'
     #{opt.program_name} compact\\!
 
-To see the default directories ri will search, run:
+To see the default directories #{opt.program_name} will search, run:
 
     #{opt.program_name} --list-doc-dirs
 
-Specifying the --system, --site, --home, --gems or --doc-dir options will
-limit ri to searching only the specified directories.
+Specifying the --system, --site, --home, --gems, or --doc-dir options
+will limit ri to searching only the specified directories.
 
-ri options may be set in the 'RI' environment variable.
+ri options may be set in the RI environment variable.
 
-The ri pager can be set with the 'RI_PAGER' environment variable or the
-'PAGER' environment variable.
+The ri pager can be set with the RI_PAGER environment variable
+or the PAGER environment variable.
       EOT
 
       opt.separator nil
@@ -199,15 +209,15 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
       opt.separator nil
 
       opt.on("--[no-]pager",
-             "Send output directly to stdout,",
-             "rather than to a pager.") do |use_pager|
+             "Send output to a pager,",
+             "rather than directly to stdout.") do |use_pager|
         options[:use_stdout] = !use_pager
       end
 
       opt.separator nil
 
       opt.on("-T",
-             "Synonym for --no-pager") do
+             "Synonym for --no-pager.") do
         options[:use_stdout] = true
       end
 
@@ -220,7 +230,7 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
 
       opt.separator nil
 
-      opt.on("--server [PORT]", Integer,
+      opt.on("--server[=PORT]", Integer,
              "Run RDoc server on the given port.",
              "The default port is 8214.") do |port|
         options[:server] = port || 8214
@@ -235,13 +245,29 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
       formatters -= %w[html label test] # remove useless output formats
 
       opt.on("--format=NAME", "-f",
-             "Uses the selected formatter. The default",
+             "Use the selected formatter.  The default",
              "formatter is bs for paged output and ansi",
-             "otherwise. Valid formatters are:",
-             formatters.join(' '), formatters) do |value|
+             "otherwise.  Valid formatters are:",
+             "#{formatters.join(', ')}.", formatters) do |value|
         options[:formatter] = RDoc::Markup.const_get "To#{value.capitalize}"
       end
 
+      opt.separator nil
+
+      opt.on("--help", "-h",
+             "Show help and exit.") do
+        puts opts
+        exit
+      end
+
+      opt.separator nil
+
+      opt.on("--version", "-v",
+             "Output version information and exit.") do
+        puts "#{opts.program_name} #{opts.version}"
+        exit
+      end
+
       opt.separator nil
       opt.separator "Data source options:"
       opt.separator nil
@@ -273,7 +299,7 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
              "Do not include documentation from",
              "the Ruby standard library, site_lib,",
              "installed gems, or ~/.rdoc.",
-             "Use with --doc-dir") do
+             "Use with --doc-dir.") do
         options[:use_system] = false
         options[:use_site] = false
         options[:use_gems] = false
@@ -283,8 +309,8 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
       opt.separator nil
 
       opt.on("--[no-]system",
-             "Include documentation from Ruby's standard",
-             "library.  Defaults to true.") do |value|
+             "Include documentation from Ruby's",
+             "standard library.  Defaults to true.") do |value|
         options[:use_system] = value
       end
 
@@ -318,19 +344,19 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
       opt.separator nil
 
       opt.on("--[no-]profile",
-             "Run with the ruby profiler") do |value|
+             "Run with the ruby profiler.") do |value|
         options[:profile] = value
       end
 
       opt.separator nil
 
       opt.on("--dump=CACHE", File,
-             "Dumps data from an ri cache or data file") do |value|
+             "Dump data from an ri cache or data file.") do |value|
         options[:dump_path] = value
       end
     end
 
-    argv = ENV['RI'].to_s.split.concat argv
+    argv = ENV['RI'].to_s.split(' ').concat argv
 
     opts.parse! argv
 
@@ -399,6 +425,7 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
     @server      = options[:server]
     @use_stdout  = options[:use_stdout]
     @show_all    = options[:show_all]
+    @width       = options[:width]
 
     # pager process for jruby
     @jruby_pager_process = nil
@@ -769,7 +796,9 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
 
   def display document
     page do |io|
-      text = document.accept formatter(io)
+      f = formatter(io)
+      f.width = @width if @width and f.respond_to?(:width)
+      text = document.accept f
 
       io.write text
     end
@@ -902,13 +931,38 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
     display out
   end
 
+  def check_did_you_mean # :nodoc:
+    if defined? DidYouMean::SpellChecker
+      true
+    else
+      begin
+        require 'did_you_mean'
+        if defined? DidYouMean::SpellChecker
+          true
+        else
+          false
+        end
+      rescue LoadError
+        false
+      end
+    end
+  end
+
   ##
   # Expands abbreviated klass +klass+ into a fully-qualified class.  "Zl::Da"
   # will be expanded to Zlib::DataError.
 
   def expand_class klass
-    ary = classes.keys.grep(Regexp.new("\\A#{klass.gsub(/(?=::|\z)/, '[^:]*')}\\z"))
-    raise NotFoundError, klass if ary.length != 1 && ary.first != klass
+    class_names = classes.keys
+    ary = class_names.grep(Regexp.new("\\A#{klass.gsub(/(?=::|\z)/, '[^:]*')}\\z"))
+    if ary.length != 1 && ary.first != klass
+      if check_did_you_mean
+        suggestions = DidYouMean::SpellChecker.new(dictionary: class_names).correct(klass)
+        raise NotFoundError.new(klass, suggestions)
+      else
+        raise NotFoundError, klass
+      end
+    end
     ary.first
   end
 
@@ -1174,7 +1228,7 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
   # +cache+ indicate if it is a class or instance method.
 
   def load_method store, cache, klass, type, name
-    methods = store.send(cache)[klass]
+    methods = store.public_send(cache)[klass]
 
     return unless methods
 
@@ -1220,7 +1274,21 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
   def lookup_method name
     found = load_methods_matching name
 
-    raise NotFoundError, name if found.empty?
+    if found.empty?
+      if check_did_you_mean
+        methods = []
+        _, _, method_name = parse_name name
+        find_methods name do |store, klass, ancestor, types, method|
+          methods.push(*store.class_methods[klass]) if [:class, :both].include? types
+          methods.push(*store.instance_methods[klass]) if [:instance, :both].include? types
+        end
+        methods = methods.uniq
+        suggestions = DidYouMean::SpellChecker.new(dictionary: methods).correct(method_name)
+        raise NotFoundError.new(name, suggestions)
+      else
+        raise NotFoundError, name
+      end
+    end
 
     filter_methods found, name
   end
@@ -1375,7 +1443,13 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
 
     render_method_arguments out, method.arglists
     render_method_superclass out, method
-    render_method_comment out, method
+    if method.is_alias_for
+      al = method.is_alias_for
+      alias_for = store.load_method al.parent_name, "#{al.name_prefix}#{al.name}"
+      render_method_comment out, method, alias_for
+    else
+      render_method_comment out, method
+    end
   end
 
   def render_method_arguments out, arglists # :nodoc:
@@ -1387,10 +1461,22 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
     out << RDoc::Markup::Rule.new(1)
   end
 
-  def render_method_comment out, method # :nodoc:
-    out << RDoc::Markup::BlankLine.new
-    out << method.comment
-    out << RDoc::Markup::BlankLine.new
+  def render_method_comment out, method, alias_for = nil# :nodoc:
+    if alias_for
+      unless method.comment.nil? or method.comment.empty?
+        out << RDoc::Markup::BlankLine.new
+        out << method.comment
+      end
+      out << RDoc::Markup::BlankLine.new
+      out << RDoc::Markup::Paragraph.new("(This method is an alias for #{alias_for.full_name}.)")
+      out << RDoc::Markup::BlankLine.new
+      out << alias_for.comment
+      out << RDoc::Markup::BlankLine.new
+    else
+      out << RDoc::Markup::BlankLine.new
+      out << method.comment
+      out << RDoc::Markup::BlankLine.new
+    end
   end
 
   def render_method_superclass out, method # :nodoc:
@@ -1435,7 +1521,7 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
     pagers.compact.uniq.each do |pager|
       next unless pager
 
-      pager_cmd = pager.split.first
+      pager_cmd = pager.split(' ').first
 
       next unless in_path? pager_cmd
 
@@ -1465,7 +1551,11 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
   # Starts a WEBrick server for ri.
 
   def start_server
-    require 'webrick'
+    begin
+      require 'webrick'
+    rescue LoadError
+      abort "webrick is not found. You may need to `gem install webrick` to install webrick."
+    end
 
     server = WEBrick::HTTPServer.new :Port => @server
 

data/lib/rdoc/ri/formatter.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 ##
 # For RubyGems backwards compatibility
 

data/lib/rdoc/ri/paths.rb

@@ -1,5 +1,5 @@
-# frozen_string_literal: false
-require 'rdoc/ri'
+# frozen_string_literal: true
+require_relative '../rdoc'
 
 ##
 # The directories where ri data lives.  Paths can be enumerated via ::each, or
@@ -12,23 +12,9 @@ module RDoc::RI::Paths
 
   version = RbConfig::CONFIG['ruby_version']
 
-  BASE    = if RbConfig::CONFIG.key? 'ridir' then
-              File.join RbConfig::CONFIG['ridir'], version
-            else
-              File.join RbConfig::CONFIG['datadir'], 'ri', version
-            end
+  BASE    = File.join RbConfig::CONFIG['ridir'], version
 
-  homedir = begin
-              File.expand_path('~')
-            rescue ArgumentError
-            end
-
-  homedir ||= ENV['HOME'] ||
-              ENV['USERPROFILE'] || ENV['HOMEPATH'] # for 1.8 compatibility
-
-  HOMEDIR = if homedir then
-              File.join homedir, ".rdoc"
-            end
+  HOMEDIR = RDoc.home
   #:startdoc:
 
   ##

data/lib/rdoc/ri/store.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 module RDoc::RI
 
   Store = RDoc::Store # :nodoc:

data/lib/rdoc/ri/task.rb

@@ -1,10 +1,10 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 begin
   gem 'rdoc'
 rescue Gem::LoadError
 end unless defined?(RDoc)
 
-require 'rdoc/task'
+require_relative '../task'
 
 ##
 # RDoc::RI::Task creates ri data in <code>./.rdoc</code> for your project.

data/lib/rdoc/ri.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 require 'rdoc'
 
 ##

data/lib/rdoc/rubygems_hook.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 require 'rubygems/user_interaction'
 require 'fileutils'
 require 'rdoc'
@@ -70,7 +70,7 @@ class RDoc::RubygemsHook
   def self.load_rdoc
     return if @rdoc_version
 
-    require 'rdoc/rdoc'
+    require_relative 'rdoc'
 
     @rdoc_version = Gem::Version.new ::RDoc::VERSION
   end
@@ -158,7 +158,7 @@ class RDoc::RubygemsHook
 
     case config_args = Gem.configuration[:rdoc]
     when String then
-      args = args.concat config_args.split
+      args = args.concat config_args.split(' ')
     when Array then
       args = args.concat config_args
     end

data/lib/rdoc/servlet.rb

@@ -1,8 +1,14 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 require 'rdoc'
+require 'erb'
 require 'time'
 require 'json'
-require 'webrick'
+
+begin
+  require 'webrick'
+rescue LoadError
+  abort "webrick is not found. You may need to `gem install webrick` to install webrick."
+end
 
 ##
 # This is a WEBrick servlet that allows you to browse ri documentation.
@@ -101,9 +107,9 @@ class RDoc::Servlet < WEBrick::HTTPServlet::AbstractServlet
     res.body = File.read asset_path
 
     res.content_type = case req.path
-                       when /css$/ then 'text/css'
-                       when /js$/  then 'application/javascript'
-                       else             'application/octet-stream'
+                       when /\.css\z/ then 'text/css'
+                       when /\.js\z/  then 'application/javascript'
+                       else                'application/octet-stream'
                        end
   end
 
@@ -111,7 +117,7 @@ class RDoc::Servlet < WEBrick::HTTPServlet::AbstractServlet
   # GET request entry point.  Fills in +res+ for the path, etc. in +req+.
 
   def do_GET req, res
-    req.path.sub!(/^#{Regexp.escape @mount_path}/o, '') if @mount_path
+    req.path.sub!(/\A#{Regexp.escape @mount_path}/, '') if @mount_path
 
     case req.path
     when '/' then
@@ -144,11 +150,14 @@ class RDoc::Servlet < WEBrick::HTTPServlet::AbstractServlet
   # +generator+ is used to create the page.
 
   def documentation_page store, generator, path, req, res
-    name = path.sub(/.html$/, '').gsub '/', '::'
+    text_name = path.chomp '.html'
+    name = text_name.gsub '/', '::'
 
     if klass = store.find_class_or_module(name) then
       res.body = generator.generate_class klass
-    elsif page = store.find_text_page(name.sub(/_([^_]*)$/, '.\1')) then
+    elsif page = store.find_text_page(name.sub(/_([^_]*)\z/, '.\1')) then
+      res.body = generator.generate_page page
+    elsif page = store.find_text_page(text_name.sub(/_([^_]*)\z/, '.\1')) then
       res.body = generator.generate_page page
     else
       not_found generator, req, res
@@ -217,7 +226,7 @@ exception:
 <pre>#{ERB::Util.html_escape exception.message}</pre>
 
 <p>Please report this to the
-<a href="https://github.com/rdoc/rdoc/issues">RDoc issues tracker</a>.  Please
+<a href="https://github.com/ruby/rdoc/issues">RDoc issues tracker</a>.  Please
 include the RDoc version, the URI above and exception class, message and
 backtrace.  If you're viewing a gem's documentation, include the gem name and
 version.  If you're viewing Ruby's documentation, include the version of ruby.
@@ -415,7 +424,7 @@ version.  If you're viewing Ruby's documentation, include the version of ruby.
       RDoc::Store.new RDoc::RI::Paths.system_dir, :system
     when 'site' then
       RDoc::Store.new RDoc::RI::Paths.site_dir, :site
-    when /^extra-(\d+)$/ then
+    when /\Aextra-(\d+)\z/ then
       index = $1.to_i - 1
       ri_dir = installed_docs[index][4]
       RDoc::Store.new ri_dir, :extra
@@ -427,14 +436,14 @@ version.  If you're viewing Ruby's documentation, include the version of ruby.
       end
 
       raise WEBrick::HTTPStatus::NotFound,
-            "Could not find gem \"#{source_name}\". Are you sure you installed it?" unless ri_dir
+            "Could not find gem \"#{ERB::Util.html_escape(source_name)}\". Are you sure you installed it?" unless ri_dir
 
       store = RDoc::Store.new ri_dir, type
 
       return store if File.exist? store.cache_path
 
       raise WEBrick::HTTPStatus::NotFound,
-            "Could not find documentation for \"#{source_name}\". Please run `gem rdoc --ri gem_name`"
+            "Could not find documentation for \"#{ERB::Util.html_escape(source_name)}\". Please run `gem rdoc --ri gem_name`"
 
     end
   end

data/lib/rdoc/single_class.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 ##
 # A singleton class
 

data/lib/rdoc/stats/normal.rb

@@ -1,5 +1,10 @@
-# frozen_string_literal: false
-require 'io/console/size'
+# frozen_string_literal: true
+begin
+  require 'io/console/size'
+rescue LoadError
+  # for JRuby
+  require 'io/console'
+end
 
 ##
 # Stats printer that prints just the files being documented with a progress
@@ -21,27 +26,28 @@ class RDoc::Stats::Normal < RDoc::Stats::Quiet
                            files_so_far,
                            @num_files)
 
-    # Print a progress bar, but make sure it fits on a single line. Filename
-    # will be truncated if necessary.
-    terminal_width = IO.console_size[1].to_i.nonzero? || 80
-    max_filename_size = terminal_width - progress_bar.size
-
-    if filename.size > max_filename_size then
-      # Turn "some_long_filename.rb" to "...ong_filename.rb"
-      filename = filename[(filename.size - max_filename_size) .. -1]
-      filename[0..2] = "..."
-    end
-
-    line = "#{progress_bar}#{filename}"
     if $stdout.tty?
+      # Print a progress bar, but make sure it fits on a single line. Filename
+      # will be truncated if necessary.
+      size = IO.respond_to?(:console_size) ? IO.console_size : IO.console.winsize
+      terminal_width = size[1].to_i.nonzero? || 80
+      max_filename_size = (terminal_width - progress_bar.size) - 1
+
+      if filename.size > max_filename_size then
+        # Turn "some_long_filename.rb" to "...ong_filename.rb"
+        filename = filename[(filename.size - max_filename_size) .. -1]
+        filename[0..2] = "..."
+      end
+
       # Clean the line with whitespaces so that leftover output from the
       # previous line doesn't show up.
-      $stdout.print("\r" << (" " * @last_width) << ("\b" * @last_width) << "\r") if @last_width && @last_width > 0
-      @last_width = line.size
-      $stdout.print("#{line}\r")
+      $stdout.print("\r\e[K") if @last_width && @last_width > 0
+      @last_width = progress_bar.size + filename.size
+      term = "\r"
     else
-      $stdout.puts(line)
+      term = "\n"
     end
+    $stdout.print(progress_bar, filename, term)
     $stdout.flush
   end
 

data/lib/rdoc/stats/quiet.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 ##
 # Stats printer that prints nothing
 

data/lib/rdoc/stats/verbose.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 ##
 # Stats printer that prints everything documented, including the documented
 # status

data/lib/rdoc/stats.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 ##
 # RDoc statistics collector which prints a summary and report of a project's
 # documentation totals.