rdoc 6.13.0 → 6.17.0

data/lib/rdoc/options.rb

@@ -327,7 +327,7 @@ class RDoc::Options
 
   ##
   # Warn if rdoc-ref links can't be resolved
-  # Default is +false+
+  # Default is +true+
 
   attr_accessor :warn_missing_rdoc_ref
 
@@ -363,7 +363,37 @@ class RDoc::Options
   # Words to be ignored in autolink cross-references
   attr_accessor :autolink_excluded_words
 
-  def initialize loaded_options = nil # :nodoc:
+  ##
+  # The prefix to use for class and module page paths
+
+  attr_accessor :class_module_path_prefix
+
+  ##
+  # The prefix to use for file page paths
+
+  attr_accessor :file_path_prefix
+
+  ##
+  # The preferred root URL for the documentation
+
+  attr_accessor :canonical_root
+
+  ##
+  # Custom footer content configuration for themes that support it.
+  # Currently only supported by the Aliki theme.
+  #
+  # A hash where keys are column titles and values are hashes of link text => URL pairs.
+  # Each column will be displayed in the upper footer section.
+  #
+  # Example:
+  #   {
+  #     "DOCUMENTATION" => {"Home" => "/index.html", "Guide" => "/guide.html"},
+  #     "RESOURCES" => {"RDoc" => "https://ruby.github.io/rdoc/", "GitHub" => "https://github.com/ruby/rdoc"}
+  #   }
+
+  attr_accessor :footer_content
+
+  def initialize(loaded_options = nil) # :nodoc:
     init_ivars
     override loaded_options if loaded_options
   end
@@ -381,10 +411,9 @@ class RDoc::Options
     @files = nil
     @force_output = false
     @force_update = true
-    @generator = nil
-    @generator_name = nil
-    @generator_options = []
+    @generator_name = "darkfish"
     @generators = RDoc::RDoc::GENERATORS
+    @generator_options = []
     @hyperlink_all = false
     @line_numbers = false
     @locale = nil
@@ -417,9 +446,13 @@ class RDoc::Options
     @charset = @encoding.name
     @skip_tests = true
     @apply_default_exclude = true
+    @class_module_path_prefix = nil
+    @file_path_prefix = nil
+    @canonical_root = nil
+    @footer_content = nil
   end
 
-  def init_with map # :nodoc:
+  def init_with(map) # :nodoc:
     init_ivars
 
     encoding = map['encoding']
@@ -445,16 +478,17 @@ class RDoc::Options
 
     @apply_default_exclude   = map['apply_default_exclude']
     @autolink_excluded_words = map['autolink_excluded_words']
+    @footer_content          = map['footer_content']
 
     @rdoc_include = sanitize_path map['rdoc_include']
     @static_path  = sanitize_path map['static_path']
   end
 
-  def yaml_initialize tag, map # :nodoc:
+  def yaml_initialize(tag, map) # :nodoc:
     init_with map
   end
 
-  def override map # :nodoc:
+  def override(map) # :nodoc:
     if map.has_key?('encoding')
       encoding = map['encoding']
       @encoding = encoding ? Encoding.find(encoding) : encoding
@@ -480,6 +514,8 @@ class RDoc::Options
     @webcvs         = map['webcvs']         if map.has_key?('webcvs')
     @autolink_excluded_words = map['autolink_excluded_words'] if map.has_key?('autolink_excluded_words')
     @apply_default_exclude = map['apply_default_exclude'] if map.has_key?('apply_default_exclude')
+    @canonical_root = map['canonical_root'] if map.has_key?('canonical_root')
+    @footer_content = map['footer_content'] if map.has_key?('footer_content')
 
     @warn_missing_rdoc_ref = map['warn_missing_rdoc_ref'] if map.has_key?('warn_missing_rdoc_ref')
 
@@ -491,7 +527,7 @@ class RDoc::Options
     end
   end
 
-  def == other # :nodoc:
+  def ==(other) # :nodoc:
     self.class === other and
       @encoding       == other.encoding       and
       @embed_mixins   == other.embed_mixins   and
@@ -683,7 +719,7 @@ class RDoc::Options
   ##
   # Parses command line options.
 
-  def parse argv
+  def parse(argv)
     ignore_invalid = true
 
     argv.insert(0, *ENV['RDOCOPT'].split) if ENV['RDOCOPT']
@@ -1194,9 +1230,6 @@ Usage: #{opt.program_name} [options] [names...]
       opt.separator nil
     end
 
-    setup_generator 'darkfish' if
-      argv.grep(/\A(-f|--fmt|--format|-r|-R|--ri|--ri-site)\b/).empty?
-
     deprecated = []
     invalid = []
 
@@ -1214,10 +1247,7 @@ Usage: #{opt.program_name} [options] [names...]
       retry
     end
 
-    unless @generator then
-      @generator = RDoc::Generator::Darkfish
-      @generator_name = 'darkfish'
-    end
+    setup_generator unless @generator
 
     if @pipe and not argv.empty? then
       @pipe = false
@@ -1262,14 +1292,14 @@ Usage: #{opt.program_name} [options] [names...]
   ##
   # Set quietness to +bool+
 
-  def quiet= bool
+  def quiet=(bool)
     @verbosity = bool ? 0 : 1
   end
 
   ##
   # Removes directories from +path+ that are outside the current directory
 
-  def sanitize_path path
+  def sanitize_path(path)
     require 'pathname'
     dot = Pathname.new('.').expand_path
 
@@ -1296,7 +1326,7 @@ Usage: #{opt.program_name} [options] [names...]
   # the options instance.  This allows generators to add custom options or set
   # default options.
 
-  def setup_generator generator_name = @generator_name
+  def setup_generator(generator_name = @generator_name)
     @generator = @generators[generator_name]
 
     unless @generator then
@@ -1318,7 +1348,7 @@ Usage: #{opt.program_name} [options] [names...]
   ##
   # Finds the template dir for +template+
 
-  def template_dir_for template
+  def template_dir_for(template)
     template_path = File.join 'rdoc', 'generator', 'template', template
 
     $LOAD_PATH.map do |path|
@@ -1335,7 +1365,7 @@ Usage: #{opt.program_name} [options] [names...]
   # When +:all+ is passed, visibility is set to +:private+, similarly to
   # RDOCOPT="--all", see #visibility for more information.
 
-  def visibility= visibility
+  def visibility=(visibility)
     case visibility
     when :all
       @visibility = :private
@@ -1347,7 +1377,7 @@ Usage: #{opt.program_name} [options] [names...]
   ##
   # Displays a warning using Kernel#warn if we're being verbose
 
-  def warn message
+  def warn(message)
     super message if @verbosity > 1
   end
 

data/lib/rdoc/parser/c.rb

@@ -168,7 +168,7 @@ class RDoc::Parser::C < RDoc::Parser
   # Prepares for parsing a C file.  See RDoc::Parser#initialize for details on
   # the arguments.
 
-  def initialize top_level, content, options, stats
+  def initialize(top_level, content, options, stats)
     super
 
     @known_classes = RDoc::KNOWN_CLASSES.dup
@@ -193,7 +193,7 @@ class RDoc::Parser::C < RDoc::Parser
 
     @enclosure_dependencies.extend TSort
 
-    def @enclosure_dependencies.tsort_each_node &block
+    def @enclosure_dependencies.tsort_each_node(&block)
       each_key(&block)
     rescue TSort::Cyclic => e
       cycle_vars = e.message.scan(/"(.*?)"/).flatten
@@ -211,7 +211,7 @@ class RDoc::Parser::C < RDoc::Parser
       retry
     end
 
-    def @enclosure_dependencies.tsort_each_child node, &block
+    def @enclosure_dependencies.tsort_each_child(node, &block)
       fetch(node, []).each(&block)
     end
   end
@@ -519,7 +519,7 @@ class RDoc::Parser::C < RDoc::Parser
   # Finds the comment for an alias on +class_name+ from +new_name+ to
   # +old_name+
 
-  def find_alias_comment class_name, new_name, old_name
+  def find_alias_comment(class_name, new_name, old_name)
     content =~ %r%((?>/\*.*?\*/\s+))
                   rb_define_alias\(\s*#{Regexp.escape class_name}\s*,
                                    \s*"#{Regexp.escape new_name}"\s*,
@@ -537,7 +537,7 @@ class RDoc::Parser::C < RDoc::Parser
   # +read+ and +write+ are the read/write flags ('1' or '0').  Either both or
   # neither must be provided.
 
-  def find_attr_comment var_name, attr_name, read = nil, write = nil
+  def find_attr_comment(var_name, attr_name, read = nil, write = nil)
     attr_name = Regexp.escape attr_name
 
     rw = if read and write then
@@ -570,7 +570,7 @@ class RDoc::Parser::C < RDoc::Parser
   ##
   # Generate a Ruby-method table
 
-  def gen_body_table file_content
+  def gen_body_table(file_content)
     table = {}
     file_content.scan(%r{
       ((?>/\*.*?\*/\s*)?)
@@ -594,7 +594,7 @@ class RDoc::Parser::C < RDoc::Parser
   ##
   # Find the C code corresponding to a Ruby method
 
-  def find_body class_name, meth_name, meth_obj, file_content, quiet = false
+  def find_body(class_name, meth_name, meth_obj, file_content, quiet = false)
     if file_content
       @body_table ||= {}
       @body_table[file_content] ||= gen_body_table file_content
@@ -607,8 +607,6 @@ class RDoc::Parser::C < RDoc::Parser
       body = args[1]
       offset, = args[2]
 
-      comment.remove_private if comment
-
       # try to find the whole body
       body = $& if /#{Regexp.escape body}[^(]*?\{.*?^\}/m =~ file_content
 
@@ -621,11 +619,10 @@ class RDoc::Parser::C < RDoc::Parser
       override_comment = find_override_comment class_name, meth_obj
       comment = override_comment if override_comment
 
-      comment.normalize
       find_modifiers comment, meth_obj if comment
 
       #meth_obj.params = params
-      meth_obj.start_collecting_tokens
+      meth_obj.start_collecting_tokens(:c)
       tk = { :line_no => 1, :char_no => 1, :text => body }
       meth_obj.add_token tk
       meth_obj.comment = comment
@@ -639,10 +636,9 @@ class RDoc::Parser::C < RDoc::Parser
 
       find_body class_name, args[3], meth_obj, file_content, true
 
-      comment.normalize
       find_modifiers comment, meth_obj
 
-      meth_obj.start_collecting_tokens
+      meth_obj.start_collecting_tokens(:c)
       tk = { :line_no => 1, :char_no => 1, :text => body }
       meth_obj.add_token tk
       meth_obj.comment = comment
@@ -663,7 +659,6 @@ class RDoc::Parser::C < RDoc::Parser
       comment = find_override_comment class_name, meth_obj
 
       if comment then
-        comment.normalize
         find_modifiers comment, meth_obj
         meth_obj.comment = comment
 
@@ -719,7 +714,7 @@ class RDoc::Parser::C < RDoc::Parser
   #    */
   #   VALUE cFoo = rb_define_class("Foo", rb_cObject);
 
-  def find_class_comment class_name, class_mod
+  def find_class_comment(class_name, class_mod)
     comment = nil
 
     if @content =~ %r%
@@ -742,7 +737,6 @@ class RDoc::Parser::C < RDoc::Parser
     end
 
     comment = new_comment comment, @top_level, :c
-    comment.normalize
 
     look_for_directives_in class_mod, comment
 
@@ -752,7 +746,7 @@ class RDoc::Parser::C < RDoc::Parser
   ##
   # Generate a const table
 
-  def gen_const_table file_content
+  def gen_const_table(file_content)
     table = {}
     @content.scan(%r{
       (?<doc>(?>^\s*/\*.*?\*/\s+))
@@ -806,27 +800,24 @@ class RDoc::Parser::C < RDoc::Parser
   ##
   # Handles modifiers in +comment+ and updates +meth_obj+ as appropriate.
 
-  def find_modifiers comment, meth_obj
-    comment.normalize
-    meth_obj.call_seq = comment.extract_call_seq
-
+  def find_modifiers(comment, meth_obj)
     look_for_directives_in meth_obj, comment
   end
 
   ##
   # Finds a <tt>Document-method</tt> override for +meth_obj+ on +class_name+
 
-  def find_override_comment class_name, meth_obj
+  def find_override_comment(class_name, meth_obj)
     name = Regexp.escape meth_obj.name
     prefix = Regexp.escape meth_obj.name_prefix
 
     comment = if @content =~ %r%Document-method:
                                 \s+#{class_name}#{prefix}#{name}
                                 \s*?\n((?>.*?\*/))%xm then
-                "/*#{$1}"
+                "/*\n#{$1}"
               elsif @content =~ %r%Document-method:
                                    \s#{name}\s*?\n((?>.*?\*/))%xm then
-                "/*#{$1}"
+                "/*\n#{$1}"
               end
 
     return unless comment
@@ -1060,18 +1051,21 @@ class RDoc::Parser::C < RDoc::Parser
   ##
   # Registers a singleton class +sclass_var+ as a singleton of +class_var+
 
-  def handle_singleton sclass_var, class_var
-    class_name = @known_classes[class_var]
-
-    @known_classes[sclass_var]     = class_name
-    @singleton_classes[sclass_var] = class_name
+  def handle_singleton(sclass_var, class_var)
+    if (klass = @classes[class_var])
+      @classes[sclass_var] = klass
+    end
+    if (class_name = @known_classes[class_var])
+      @known_classes[sclass_var]     = class_name
+      @singleton_classes[sclass_var] = class_name
+    end
   end
 
   ##
   # Loads the variable map with the given +name+ from the RDoc::Store, if
   # present.
 
-  def load_variable_map map_name
+  def load_variable_map(map_name)
     return {} unless files = @store.cache[map_name]
     return {} unless name_map = files[@file_name]
 
@@ -1101,36 +1095,11 @@ class RDoc::Parser::C < RDoc::Parser
   # This method modifies the +comment+
   # Both :main: and :title: directives are deprecated and will be removed in RDoc 7.
 
-  def look_for_directives_in context, comment
-    @preprocess.handle comment, context do |directive, param|
-      case directive
-      when 'main' then
-        @options.main_page = param
-
-        warn <<~MSG
-          The :main: directive is deprecated and will be removed in RDoc 7.
-
-          You can use these options to specify the initial page displayed instead:
-          - `--main=#{param}` via the command line
-          - `rdoc.main = "#{param}"` if you use `RDoc::Task`
-          - `main_page: #{param}` in your `.rdoc_options` file
-        MSG
-        ''
-      when 'title' then
-        @options.default_title = param if @options.respond_to? :default_title=
-
-        warn <<~MSG
-          The :title: directive is deprecated and will be removed in RDoc 7.
-
-          You can use these options to specify the title displayed instead:
-          - `--title=#{param}` via the command line
-          - `rdoc.title = "#{param}"` if you use `RDoc::Task`
-          - `title: #{param}` in your `.rdoc_options` file
-        MSG
-        ''
-      end
-    end
-
+  def look_for_directives_in(context, comment)
+    comment.text, format = @preprocess.run_pre_processes(comment.text, context, comment.line || 1, :c)
+    comment.format = format if format
+    @preprocess.run_post_processes(comment, context)
+    comment.normalized = true
     comment
   end
 
@@ -1138,7 +1107,7 @@ class RDoc::Parser::C < RDoc::Parser
   # Extracts parameters from the +method_body+ and returns a method
   # parameter string.  Follows 1.9.3dev's scan-arg-spec, see README.EXT
 
-  def rb_scan_args method_body
+  def rb_scan_args(method_body)
     method_body =~ /rb_scan_args\((.*?)\)/m
     return '(*args)' unless $1
 
@@ -1249,7 +1218,7 @@ class RDoc::Parser::C < RDoc::Parser
   ##
   # Creates a RDoc::Comment instance.
 
-  def new_comment text = nil, location = nil, language = nil
+  def new_comment(text = nil, location = nil, language = nil)
     RDoc::Comment.new(text, location, language).tap do |comment|
       comment.format = @markup
     end

data/lib/rdoc/parser/changelog.rb

@@ -23,7 +23,7 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
   # Continued function listings are joined together as a single entry.
   # Continued descriptions are joined to make a single paragraph.
 
-  def continue_entry_body entry_body, continuation
+  def continue_entry_body(entry_body, continuation)
     return unless last = entry_body.last
 
     if last =~ /\)\s*\z/ and continuation =~ /\A\(/ then
@@ -41,7 +41,7 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
   ##
   # Creates an RDoc::Markup::Document given the +groups+ of ChangeLog entries.
 
-  def create_document groups
+  def create_document(groups)
     doc = RDoc::Markup::Document.new
     doc.omit_headings_below = 2
     doc.file = @top_level
@@ -63,7 +63,7 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
   # Returns a list of ChangeLog entries an RDoc::Markup nodes for the given
   # +entries+.
 
-  def create_entries entries
+  def create_entries(entries)
     out = []
 
     entries.each do |entry, items|
@@ -80,7 +80,7 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
   # Returns an RDoc::Markup::List containing the given +items+ in the
   # ChangeLog
 
-  def create_items items
+  def create_items(items)
     list = RDoc::Markup::List.new :NOTE
 
     items.each do |item|
@@ -100,7 +100,7 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
   ##
   # Groups +entries+ by date.
 
-  def group_entries entries
+  def group_entries(entries)
     @time_cache ||= {}
     entries.group_by do |title, _|
       begin
@@ -260,7 +260,7 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
     # RDoc::Parser::ChangeLog::Git::LogEntry list for the given
     # +entries+.
 
-    def create_entries entries
+    def create_entries(entries)
       # git log entries have no strictly itemized style like the old
       # style, just assume Markdown.
       entries.map do |commit, entry|
@@ -296,7 +296,7 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
         "label-#{commit}"
       end
 
-      def label context = nil
+      def label(context = nil)
         aref
       end
 
@@ -311,7 +311,7 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
         end + " {#{author}}[mailto:#{email}]"
       end
 
-      def accept visitor
+      def accept(visitor)
         visitor.accept_heading self
         begin
           if visitor.respond_to?(:code_object=)
@@ -328,7 +328,7 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
         end
       end
 
-      def pretty_print q # :nodoc:
+      def pretty_print(q) # :nodoc:
         q.group(2, '[log_entry: ', ']') do
           q.text commit
           q.text ','