rdoc 6.7.0 → 6.13.1

data/lib/rdoc/ri/driver.rb

@@ -79,6 +79,7 @@ class RDoc::RI::Driver
     options[:interactive] = false
     options[:profile]     = false
     options[:show_all]    = false
+    options[:expand_refs] = true
     options[:use_stdout]  = !$stdout.tty?
     options[:width]       = 72
 
@@ -110,10 +111,6 @@ class RDoc::RI::Driver
     options = default_options
 
     opts = OptionParser.new do |opt|
-      opt.accept File do |file,|
-        File.readable?(file) and not File.directory?(file) and file
-      end
-
       opt.program_name = File.basename $0
       opt.version = RDoc::VERSION
       opt.release = nil
@@ -249,6 +246,12 @@ or the PAGER environment variable.
 
       opt.separator nil
 
+      opt.on("--[no-]expand-refs", "Expand rdoc-refs at the end of output") do |value|
+        options[:expand_refs] = value
+      end
+
+      opt.separator nil
+
       opt.on("--help", "-h",
              "Show help and exit.") do
         puts opts
@@ -345,9 +348,17 @@ or the PAGER environment variable.
 
       opt.separator nil
 
-      opt.on("--dump=CACHE", File,
+      opt.on("--dump=CACHE",
              "Dump data from an ri cache or data file.") do |value|
-        options[:dump_path] = value
+        unless File.readable?(value)
+          abort "#{value.inspect} is not readable"
+        end
+
+        if File.directory?(value)
+          abort "#{value.inspect} is a directory"
+        end
+
+        options[:dump_path] = File.new(value)
       end
     end
 
@@ -409,7 +420,7 @@ or the PAGER environment variable.
                          *options[:extra_doc_dirs]) do |path, type|
       @doc_dirs << path
 
-      store = RDoc::RI::Store.new path, type
+      store = RDoc::RI::Store.new(RDoc::Options.new, path: path, type: type)
       store.load_cache
       @stores << store
     end
@@ -421,6 +432,7 @@ or the PAGER environment variable.
     @use_stdout  = options[:use_stdout]
     @show_all    = options[:show_all]
     @width       = options[:width]
+    @expand_refs = options[:expand_refs]
   end
 
   ##
@@ -506,7 +518,7 @@ or the PAGER environment variable.
     with.each do |incl|
       out << RDoc::Markup::Paragraph.new(incl.name)
       out << RDoc::Markup::BlankLine.new
-      out << incl.comment
+      out << incl.comment.parse
     end
 
     unless wout.empty? then
@@ -530,7 +542,7 @@ or the PAGER environment variable.
 
     if include.comment then
       out << RDoc::Markup::BlankLine.new
-      out << include.comment
+      out << include.comment.parse
     end
   end
 
@@ -545,11 +557,8 @@ or the PAGER environment variable.
   # Looks up the method +name+ and adds it to +out+
 
   def add_method out, name
-    filtered   = lookup_method name
-
-    method_out = method_document name, filtered
-
-    out.concat method_out.parts
+    filtered = lookup_method name
+    method_document out, name, filtered
   end
 
   ##
@@ -641,18 +650,19 @@ or the PAGER environment variable.
 
     add_also_in out, also_in
 
+    expand_rdoc_refs_at_the_bottom(out)
     out
   end
 
   ##
   # Adds the class +comment+ to +out+.
 
-  def class_document_comment out, comment # :nodoc:
-    unless comment.empty? then
+  def class_document_comment out, document # :nodoc:
+    unless document.empty? then
       out << RDoc::Markup::Rule.new(1)
 
-      if comment.merged? then
-        parts = comment.parts
+      if document.merged? then
+        parts = document.parts
         parts = parts.zip [RDoc::Markup::BlankLine.new] * parts.length
         parts.flatten!
         parts.pop
@@ -677,7 +687,7 @@ or the PAGER environment variable.
     constants = klass.constants.sort_by { |constant| constant.name }
 
     list.items.concat constants.map { |constant|
-      parts = constant.comment.parts if constant.comment
+      parts = constant.comment.parse.parts
       parts << RDoc::Markup::Paragraph.new('[not documented]') if
         parts.empty?
 
@@ -744,7 +754,7 @@ or the PAGER environment variable.
     complete_klass  name, klass, selector, method, completions
     complete_method name, klass, selector,         completions
 
-    completions.sort.uniq
+    completions.uniq.select {|s| s.start_with? name }.sort
   end
 
   def complete_klass name, klass, selector, method, completions # :nodoc:
@@ -779,7 +789,15 @@ or the PAGER environment variable.
         completions << "#{klass}#{selector}"
       end
 
-      completions.concat methods
+      methods.each do |klass_sel_method|
+        match = klass_sel_method.match(/^(.+)(#|\.|::)([^#.:]+)$/)
+        # match[2] is `::` for class method and `#` for instance method.
+        # To be consistent with old completion that completes `['Foo#i', 'Foo::c']` for `Foo.`,
+        # `.` should be a wildcard for both `#` and `::` here.
+        if match && match[2] == selector || selector == '.'
+          completions << match[1] + selector + match[3]
+        end
+      end
     end
   end
 
@@ -820,6 +838,8 @@ or the PAGER environment variable.
 
     add_method out, name
 
+    expand_rdoc_refs_at_the_bottom(out)
+
     display out
   end
 
@@ -894,7 +914,7 @@ or the PAGER environment variable.
 
     page = store.load_page page_name
 
-    display page.comment
+    display page.comment.parse
   end
 
   ##
@@ -1195,7 +1215,8 @@ or the PAGER environment variable.
 
     store.load_method klass, "#{type}#{method}"
   rescue RDoc::Store::MissingFileError => e
-    comment = RDoc::Comment.new("missing documentation at #{e.file}").parse
+    comment = RDoc::Comment.new("missing documentation at #{e.file}")
+    comment.parse
 
     method = RDoc::AnyMethod.new nil, name
     method.comment = comment
@@ -1251,9 +1272,7 @@ or the PAGER environment variable.
   ##
   # Builds a RDoc::Markup::Document from +found+, +klasses+ and +includes+
 
-  def method_document name, filtered
-    out = RDoc::Markup::Document.new
-
+  def method_document out, name, filtered
     out << RDoc::Markup::Heading.new(1, name)
     out << RDoc::Markup::BlankLine.new
 
@@ -1357,13 +1376,13 @@ or the PAGER environment variable.
   # documentable items the class is added to +also_in+ instead.
 
   def render_class out, store, klass, also_in # :nodoc:
-    comment = klass.comment
+    document = klass.comment.parse
     # TODO the store's cache should always return an empty Array
     class_methods    = store.class_methods[klass.full_name]    || []
     instance_methods = store.instance_methods[klass.full_name] || []
     attributes       = store.attributes[klass.full_name]       || []
 
-    if comment.empty? and
+    if document.empty? and
        instance_methods.empty? and class_methods.empty? then
       also_in << store
       return
@@ -1371,7 +1390,7 @@ or the PAGER environment variable.
 
     add_from out, store
 
-    class_document_comment out, comment
+    class_document_comment out, document
 
     if class_methods or instance_methods or not klass.constants.empty? then
       out << RDoc::Markup::Rule.new(1)
@@ -1419,16 +1438,16 @@ or the PAGER environment variable.
     if alias_for
       unless method.comment.nil? or method.comment.empty?
         out << RDoc::Markup::BlankLine.new
-        out << method.comment
+        out << method.comment.parse
       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 << alias_for.comment.parse
       out << RDoc::Markup::BlankLine.new
     else
       out << RDoc::Markup::BlankLine.new
-      out << method.comment
+      out << method.comment.parse
       out << RDoc::Markup::BlankLine.new
     end
   end
@@ -1510,4 +1529,38 @@ or the PAGER environment variable.
     server.start
   end
 
+  RDOC_REFS_REGEXP = /\[rdoc-ref:([\w.]+)(@.*)?\]/
+
+  def expand_rdoc_refs_at_the_bottom(out)
+    return unless @expand_refs
+
+    extracted_rdoc_refs = []
+
+    out.each do |part|
+      content = if part.respond_to?(:text)
+        part.text
+      else
+        next
+      end
+
+      rdoc_refs = content.scan(RDOC_REFS_REGEXP).uniq.map do |file_name, _anchor|
+        file_name
+      end
+
+      extracted_rdoc_refs.concat(rdoc_refs)
+    end
+
+    found_pages = extracted_rdoc_refs.map do |ref|
+      begin
+        @stores.first.load_page(ref)
+      rescue RDoc::Store::MissingFileError
+      end
+    end.compact
+
+    found_pages.each do |page|
+      out << RDoc::Markup::Heading.new(4, "Expanded from #{page.full_name}")
+      out << RDoc::Markup::BlankLine.new
+      out << page.comment.parse
+    end
+  end
 end

data/lib/rdoc/rubygems_hook.rb

@@ -3,13 +3,19 @@ require 'rubygems/user_interaction'
 require 'fileutils'
 require_relative '../rdoc'
 
-##
-# Gem::RDoc provides methods to generate RDoc and ri data for installed gems
-# upon gem installation.
+# We define the following two similar name classes in this file:
 #
-# This file is automatically required by RubyGems 1.9 and newer.
+# - RDoc::RubyGemsHook
+# - RDoc::RubygemsHook
+#
+# RDoc::RubyGemsHook is the main class that has real logic.
+#
+# RDoc::RubygemsHook is a class that is only for
+# compatibility. RDoc::RubygemsHook is used by RubyGems directly. We
+# can remove this when all maintained RubyGems remove
+# `rubygems/rdoc.rb`.
 
-class RDoc::RubygemsHook
+class RDoc::RubyGemsHook
 
   include Gem::UserInteraction
   extend  Gem::UserInteraction
@@ -45,7 +51,7 @@ class RDoc::RubygemsHook
   # Post installs hook that generates documentation for each specification in
   # +specs+
 
-  def self.generation_hook installer, specs
+  def self.generate installer, specs
     start = Time.now
     types = installer.document
 
@@ -64,6 +70,10 @@ class RDoc::RubygemsHook
     say "Done installing documentation for #{names} after #{duration} seconds"
   end
 
+  def self.remove uninstaller
+    new(uninstaller.spec).remove
+  end
+
   ##
   # Loads the RDoc generator
 
@@ -171,20 +181,14 @@ class RDoc::RubygemsHook
       options = ::RDoc::Options.new
       options.default_title = "#{@spec.full_name} Documentation"
       options.parse args
+      options.quiet = !Gem.configuration.really_verbose
+      options.finish
     end
 
-    options.quiet = !Gem.configuration.really_verbose
-
     @rdoc = new_rdoc
     @rdoc.options = options
 
-    store = RDoc::Store.new
-    store.encoding = options.encoding
-    store.dry_run  = options.dry_run
-    store.main     = options.main_page
-    store.title    = options.title
-
-    @rdoc.store = store
+    @rdoc.store = RDoc::Store.new(options)
 
     say "Parsing documentation for #{@spec.full_name}"
 
@@ -246,3 +250,75 @@ class RDoc::RubygemsHook
   end
 
 end
+
+# This class is referenced by RubyGems to create documents.
+# All implementations are moved to the above RubyGemsHook.
+#
+# This class does nothing when this RDoc is installed as a normal gem
+# or a bundled gem.
+#
+# This class does generate/remove documents for compatibility when
+# this RDoc is installed as a default gem.
+#
+# We can remove this when all maintained RubyGems remove
+# `rubygems/rdoc.rb`.
+module RDoc
+  class RubygemsHook
+
+    attr_accessor :generate_rdoc, :generate_ri, :force
+
+    def self.default_gem?
+      !File.exist?(File.join(__dir__, "..", "rubygems_plugin.rb"))
+    end
+
+    def initialize(spec, generate_rdoc = false, generate_ri = true)
+      @spec = spec
+      @generate_rdoc = generate_rdoc
+      @generate_ri   = generate_ri
+      @force = false
+    end
+
+    def generate
+      # Do nothing if this is NOT a default gem.
+      return unless self.class.default_gem?
+
+      # Generate document for compatibility if this is a default gem.
+      hook = RubyGemsHook.new(@spec, @generate_rdoc, @generate_ri)
+      hook.force = @force
+      hook.generate
+    end
+
+    def remove
+      # Do nothing if this is NOT a default gem.
+      return unless self.class.default_gem?
+
+      # Remove generated document for compatibility if this is a
+      # default gem.
+      RubyGemsHook.new(@spec).remove
+    end
+
+    def self.generation_hook installer, specs
+      # Do nothing if this is NOT a default gem.
+      return unless default_gem?
+
+      # Generate document for compatibility if this is a default gem.
+      RubyGemsHook.generate(installer, specs)
+    end
+
+    def self.load_rdoc
+      RubyGemsHook.load_rdoc
+    end
+
+    def self.rdoc_version
+      RubyGemsHook.rdoc_version
+    end
+
+    def rdoc_installed?
+      RubyGemsHook.new(@spec).rdoc_installed?
+    end
+
+    def ri_installed?
+      RubyGemsHook.new(@spec).ri_installed?
+    end
+  end
+end

data/lib/rdoc/servlet.rb

@@ -133,7 +133,7 @@ class RDoc::Servlet < WEBrick::HTTPServlet::AbstractServlet
       show_documentation req, res
     end
   rescue WEBrick::HTTPStatus::NotFound => e
-    generator = generator_for RDoc::Store.new
+    generator = generator_for RDoc::Store.new(@options)
 
     not_found generator, req, res, e.message
   rescue WEBrick::HTTPStatus::Status
@@ -247,6 +247,7 @@ version.  If you're viewing Ruby's documentation, include the version of ruby.
     generator = RDoc::Generator::Darkfish.new store, @options
     generator.file_output = false
     generator.asset_rel_path = '..'
+    generator.setup
 
     rdoc = RDoc::RDoc.new
     rdoc.store     = store
@@ -290,7 +291,7 @@ version.  If you're viewing Ruby's documentation, include the version of ruby.
   def installed_docs
     extra_counter = 0
     ri_paths.map do |path, type|
-      store = RDoc::Store.new path, type
+      store = RDoc::Store.new(@options, path: path, type: type)
       exists = File.exist? store.cache_path
 
       case type
@@ -419,15 +420,15 @@ version.  If you're viewing Ruby's documentation, include the version of ruby.
   def store_for source_name
     case source_name
     when 'home' then
-      RDoc::Store.new RDoc::RI::Paths.home_dir, :home
+      RDoc::Store.new(@options, path: RDoc::RI::Paths.home_dir, type: :home)
     when 'ruby' then
-      RDoc::Store.new RDoc::RI::Paths.system_dir, :system
+      RDoc::Store.new(@options, path: RDoc::RI::Paths.system_dir, type: :system)
     when 'site' then
-      RDoc::Store.new RDoc::RI::Paths.site_dir, :site
+      RDoc::Store.new(@options, path: RDoc::RI::Paths.site_dir, type: :site)
     when /\Aextra-(\d+)\z/ then
       index = $1.to_i - 1
       ri_dir = installed_docs[index][4]
-      RDoc::Store.new ri_dir, :extra
+      RDoc::Store.new(@options, path: ri_dir, type: :extra)
     else
       ri_dir, type = ri_paths.find do |dir, dir_type|
         next unless dir_type == :gem
@@ -438,7 +439,7 @@ version.  If you're viewing Ruby's documentation, include the version of ruby.
       raise WEBrick::HTTPStatus::NotFound,
             "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
+      store = RDoc::Store.new(@options, path: ri_dir, type: type)
 
       return store if File.exist? store.cache_path
 

data/lib/rdoc/stats.rb

@@ -261,7 +261,7 @@ class RDoc::Stats
 
     report = []
 
-    cm.each_attribute do |attr|
+    cm.attributes.each do |attr|
       next if attr.documented?
       line = attr.line ? ":#{attr.line}" : nil
       report << "  #{attr.definition} :#{attr.name} # in file #{attr.file.full_name}#{line}\n"
@@ -331,7 +331,7 @@ class RDoc::Stats
 
     report = []
 
-    cm.each_constant do |constant|
+    cm.constants.each do |constant|
       # TODO constant aliases are listed in the summary but not reported
       # figure out what to do here
       next if constant.documented? || constant.is_alias_for

data/lib/rdoc/store.rb

@@ -94,11 +94,7 @@ class RDoc::Store
 
   attr_accessor :path
 
-  ##
-  # The RDoc::RDoc driver for this parse tree.  This allows classes consulting
-  # the documentation tree to access user-set options, for example.
-
-  attr_accessor :rdoc
+  attr_reader :options
 
   ##
   # Type of ri datastore this was loaded from.  See RDoc::RI::Driver,
@@ -124,11 +120,11 @@ class RDoc::Store
   ##
   # Creates a new Store of +type+ that will load or save to +path+
 
-  def initialize path = nil, type = nil
-    @dry_run  = false
-    @encoding = nil
-    @path     = path
-    @rdoc     = nil
+  def initialize(options, path: nil, type: nil)
+    @options  = options
+    @dry_run  = options.dry_run
+    @encoding = options.encoding
+    @path     = path || options.op_dir
     @type     = type
 
     @cache = {
@@ -139,10 +135,10 @@ class RDoc::Store
       :c_singleton_class_variables => {},
       :encoding                    => @encoding,
       :instance_methods            => {},
-      :main                        => nil,
+      :main                        => options.main_page,
       :modules                     => [],
       :pages                       => [],
-      :title                       => nil,
+      :title                       => options.title,
     }
 
     @classes_hash = {}
@@ -197,6 +193,18 @@ class RDoc::Store
     top_level
   end
 
+  ##
+  # Make sure any references to C variable names are resolved to the corresponding class.
+  #
+
+  def resolve_c_superclasses
+    @classes_hash.each_value do |klass|
+      if klass.superclass.is_a?(String) && (candidate = find_c_enclosure(klass.superclass))
+        klass.superclass = candidate
+      end
+    end
+  end
+
   ##
   # Sets the parser of +absolute_name+, unless it from a source code file.
 
@@ -754,7 +762,7 @@ class RDoc::Store
         save_method klass, method
       end
 
-      klass.each_attribute do |attribute|
+      klass.attributes.each do |attribute|
         save_method klass, attribute
       end
     end

data/lib/rdoc/task.rb

@@ -104,9 +104,8 @@ class RDoc::Task < Rake::TaskLib
   attr_accessor :name
 
   ##
-  # Comment markup format.  rdoc, rd and tomdoc are supported.  (default is
-  # 'rdoc')
-
+  # The markup format; one of: +rdoc+ (the default), +markdown+, +rd+, +tomdoc+.
+  # See {Markup Formats}[rdoc-ref:RDoc::Markup@Markup+Formats].
   attr_accessor :markup
 
   ##

data/lib/rdoc/text.rb

@@ -99,8 +99,8 @@ module RDoc::Text
   # Requires the including class to implement #formatter
 
   def markup text
-    if @store.rdoc.options
-      locale = @store.rdoc.options.locale
+    if @store.options
+      locale = @store.options.locale
     else
       locale = nil
     end

data/lib/rdoc/tom_doc.rb

@@ -3,13 +3,7 @@
 
 # A parser for TomDoc based on TomDoc 1.0.0-rc1 (02adef9b5a)
 #
-# The TomDoc specification can be found at:
-#
-# http://tomdoc.org
-#
-# The latest version of the TomDoc specification can be found at:
-#
-# https://github.com/mojombo/tomdoc/blob/master/tomdoc.md
+# The TomDoc specification can be found at http://tomdoc.org.
 #
 # To choose TomDoc as your only default format see RDoc::Options@Saved+Options
 # for instructions on setting up a <code>.rdoc_options</code> file to store

data/lib/rdoc/version.rb

@@ -5,6 +5,6 @@ module RDoc
   ##
   # RDoc version you are using
 
-  VERSION = '6.7.0'
+  VERSION = '6.13.1'
 
 end

data/lib/rdoc.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 $DEBUG_RDOC = nil
 
-# :main: README.rdoc
-
 ##
 # RDoc produces documentation for Ruby source files by parsing the source and
 # extracting the definition for classes, modules, methods, includes and
@@ -21,7 +19,7 @@ $DEBUG_RDOC = nil
 # see RDoc::Markup and refer to <tt>rdoc --help</tt> for command line usage.
 #
 # If you want to set the default markup format see
-# RDoc::Markup@Supported+Formats
+# RDoc::Markup@Markup+Formats
 #
 # If you want to store rdoc configuration in your gem (such as the default
 # markup format) see RDoc::Options@Saved+Options
@@ -188,26 +186,26 @@ module RDoc
   # programs: classes, modules, methods, and so on.
   autoload :CodeObject,     "#{__dir__}/rdoc/code_object"
 
-  autoload :Context,        "#{__dir__}/rdoc/context"
-  autoload :TopLevel,       "#{__dir__}/rdoc/top_level"
-
-  autoload :AnonClass,      "#{__dir__}/rdoc/anon_class"
-  autoload :ClassModule,    "#{__dir__}/rdoc/class_module"
-  autoload :NormalClass,    "#{__dir__}/rdoc/normal_class"
-  autoload :NormalModule,   "#{__dir__}/rdoc/normal_module"
-  autoload :SingleClass,    "#{__dir__}/rdoc/single_class"
-
-  autoload :Alias,          "#{__dir__}/rdoc/alias"
-  autoload :AnyMethod,      "#{__dir__}/rdoc/any_method"
-  autoload :MethodAttr,     "#{__dir__}/rdoc/method_attr"
-  autoload :GhostMethod,    "#{__dir__}/rdoc/ghost_method"
-  autoload :MetaMethod,     "#{__dir__}/rdoc/meta_method"
-  autoload :Attr,           "#{__dir__}/rdoc/attr"
-
-  autoload :Constant,       "#{__dir__}/rdoc/constant"
-  autoload :Mixin,          "#{__dir__}/rdoc/mixin"
-  autoload :Include,        "#{__dir__}/rdoc/include"
-  autoload :Extend,         "#{__dir__}/rdoc/extend"
-  autoload :Require,        "#{__dir__}/rdoc/require"
+  autoload :Context,        "#{__dir__}/rdoc/code_object/context"
+  autoload :TopLevel,       "#{__dir__}/rdoc/code_object/top_level"
+
+  autoload :AnonClass,      "#{__dir__}/rdoc/code_object/anon_class"
+  autoload :ClassModule,    "#{__dir__}/rdoc/code_object/class_module"
+  autoload :NormalClass,    "#{__dir__}/rdoc/code_object/normal_class"
+  autoload :NormalModule,   "#{__dir__}/rdoc/code_object/normal_module"
+  autoload :SingleClass,    "#{__dir__}/rdoc/code_object/single_class"
+
+  autoload :Alias,          "#{__dir__}/rdoc/code_object/alias"
+  autoload :AnyMethod,      "#{__dir__}/rdoc/code_object/any_method"
+  autoload :MethodAttr,     "#{__dir__}/rdoc/code_object/method_attr"
+  autoload :GhostMethod,    "#{__dir__}/rdoc/code_object/ghost_method"
+  autoload :MetaMethod,     "#{__dir__}/rdoc/code_object/meta_method"
+  autoload :Attr,           "#{__dir__}/rdoc/code_object/attr"
+
+  autoload :Constant,       "#{__dir__}/rdoc/code_object/constant"
+  autoload :Mixin,          "#{__dir__}/rdoc/code_object/mixin"
+  autoload :Include,        "#{__dir__}/rdoc/code_object/include"
+  autoload :Extend,         "#{__dir__}/rdoc/code_object/extend"
+  autoload :Require,        "#{__dir__}/rdoc/code_object/require"
 
 end