rdoc 6.7.0 → 6.13.1

data/lib/rdoc/markup/to_html_crossref.rb

@@ -58,7 +58,7 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   # Creates a link to the reference +name+ if the name exists.  If +text+ is
   # given it is used as the link text, otherwise +name+ is used.
 
-  def cross_reference name, text = nil, code = true
+  def cross_reference name, text = nil, code = true, rdoc_ref: false
     lookup = name
 
     name = name[1..-1] unless @show_hash if name[0, 1] == '#'
@@ -70,7 +70,7 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
       text ||= name
     end
 
-    link lookup, text, code
+    link lookup, text, code, rdoc_ref: rdoc_ref
   end
 
   ##
@@ -83,6 +83,8 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   def handle_regexp_CROSSREF(target)
     name = target.text
 
+    return name if @options.autolink_excluded_words&.include?(name)
+
     return name if name =~ /@[\w-]+\.[\w-]/ # labels that look like emails
 
     unless @hyperlink_all then
@@ -92,7 +94,7 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
       return name if name =~ /\A[a-z]*\z/
     end
 
-    cross_reference name
+    cross_reference name, rdoc_ref: false
   end
 
   ##
@@ -100,9 +102,14 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   # handle other schemes.
 
   def handle_regexp_HYPERLINK target
-    return cross_reference $' if target.text =~ /\Ardoc-ref:/
+    url = target.text
 
-    super
+    case url
+    when /\Ardoc-ref:/
+      cross_reference $', rdoc_ref: true
+    else
+      super
+    end
   end
 
   ##
@@ -117,8 +124,8 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
     url = target.text
 
     case url
-    when /\Ardoc-ref:/ then
-      cross_reference $'
+    when /\Ardoc-ref:/
+      cross_reference $', rdoc_ref: true
     else
       super
     end
@@ -129,16 +136,18 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   # RDoc::Markup::ToHtml to handle other schemes.
 
   def gen_url url, text
-    return super unless url =~ /\Ardoc-ref:/
-
-    name = $'
-    cross_reference name, text, name == text
+    if url =~ /\Ardoc-ref:/
+      name = $'
+      cross_reference name, text, name == text, rdoc_ref: true
+    else
+      super
+    end
   end
 
   ##
   # Creates an HTML link to +name+ with the given +text+.
 
-  def link name, text, code = true
+  def link name, text, code = true, rdoc_ref: false
     if !(name.end_with?('+@', '-@')) and name =~ /(.*[^#:])?@/
       name = $1
       label = $'
@@ -148,6 +157,9 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
 
     case ref
     when String then
+      if rdoc_ref && @options.warn_missing_rdoc_ref
+        puts "#{@from_path}: `rdoc-ref:#{name}` can't be resolved for `#{text}`"
+      end
       ref
     else
       path = ref ? ref.as_href(@from_path) : +""
@@ -172,4 +184,43 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
     end
   end
 
+  def convert_flow(flow)
+    res = []
+
+    i = 0
+    while i < flow.size
+      item = flow[i]
+      i += 1
+      case item
+      when RDoc::Markup::AttrChanger then
+        # Make "+Class#method+" a cross reference
+        if tt_tag?(item.turn_on) and
+          String === (str = flow[i]) and
+          RDoc::Markup::AttrChanger === flow[i+1] and
+          tt_tag?(flow[i+1].turn_off, true) and
+          (@options.hyperlink_all ? ALL_CROSSREF_REGEXP : CROSSREF_REGEXP).match?(str) and
+          (text = cross_reference str) != str
+        then
+          text = yield text, res if defined?(yield)
+          res << text
+          i += 2
+          next
+        end
+        off_tags res, item
+        on_tags res, item
+      when String then
+        text = convert_string(item)
+        text = yield text, res if defined?(yield)
+        res << text
+      when RDoc::Markup::RegexpHandling then
+        text = convert_regexp_handling(item)
+        text = yield text, res if defined?(yield)
+        res << text
+      else
+        raise "Unknown flow element: #{item.inspect}"
+      end
+    end
+
+    res.join('')
+  end
 end

data/lib/rdoc/markup/to_rdoc.rb

@@ -249,12 +249,12 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
   # Adds +table+ to the output
 
   def accept_table header, body, aligns
-    widths = header.zip(body) do |h, b|
-      [h.size, b.size].max
+    widths = header.zip(*body).map do |cols|
+      cols.map(&:size).max
     end
     aligns = aligns.map do |a|
       case a
-      when nil
+      when nil, :center
         :center
       when :left
         :ljust
@@ -262,12 +262,12 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
         :rjust
       end
     end
-    @res << header.zip(widths, aligns) do |h, w, a|
+    @res << header.zip(widths, aligns).map do |h, w, a|
       h.__send__(a, w)
     end.join("|").rstrip << "\n"
     @res << widths.map {|w| "-" * w }.join("|") << "\n"
     body.each do |row|
-      @res << row.zip(widths, aligns) do |t, w, a|
+      @res << row.zip(widths, aligns).map do |t, w, a|
         t.__send__(a, w)
       end.join("|").rstrip << "\n"
     end

data/lib/rdoc/markup.rb

@@ -10,19 +10,24 @@
 # RDoc::Markup and other markup formats do no output formatting, this is
 # handled by the RDoc::Markup::Formatter subclasses.
 #
-# = Supported Formats
-#
-# Besides the RDoc::Markup format, the following formats are built in to RDoc:
-#
-# markdown::
-#   The markdown format as described by
-#   http://daringfireball.net/projects/markdown/.  See RDoc::Markdown for
-#   details on the parser and supported extensions.
-# rd::
-#   The rdtool format.  See RDoc::RD for details on the parser and format.
-# tomdoc::
-#   The TomDoc format as described by http://tomdoc.org/.  See RDoc::TomDoc
-#   for details on the parser and supported extensions.
+# = Markup Formats
+#
+# +RDoc+ supports these markup formats:
+#
+# - +rdoc+:
+#   the +RDoc+ markup format;
+#   see RDoc::MarkupReference.
+# - +markdown+:
+#   The +markdown+ markup format as described in
+#   the {Markdown Guide}[https://www.markdownguide.org];
+#   see RDoc::Markdown.
+# - +rd+:
+#   the +rd+ markup format format;
+#   see RDoc::RD.
+# - +tomdoc+:
+#   the TomDoc format as described in
+#   {TomDoc for Ruby}[http://tomdoc.org];
+#   see RDoc::TomDoc.
 #
 # You can choose a markup format using the following methods:
 #

data/lib/rdoc/options.rb

@@ -233,9 +233,9 @@ class RDoc::Options
   attr_accessor :main_page
 
   ##
-  # The default markup format.  The default is 'rdoc'.  'markdown', 'tomdoc'
-  # and 'rd' are also built-in.
-
+  # The markup format.
+  # One of: +rdoc+ (the default), +markdown+, +rd+, +tomdoc+.
+  # See {Markup Formats}[rdoc-ref:RDoc::Markup@Markup+Formats].
   attr_accessor :markup
 
   ##
@@ -325,6 +325,12 @@ class RDoc::Options
 
   attr_accessor :verbosity
 
+  ##
+  # Warn if rdoc-ref links can't be resolved
+  # Default is +false+
+
+  attr_accessor :warn_missing_rdoc_ref
+
   ##
   # URL of web cvs frontend
 
@@ -344,17 +350,44 @@ class RDoc::Options
   # Indicates if files of test suites should be skipped
   attr_accessor :skip_tests
 
+  ##
+  # Embed mixin methods, attributes, and constants into class documentation. Set via
+  # +--[no-]embed-mixins+ (Default is +false+.)
+  attr_accessor :embed_mixins
+
+  ##
+  # Exclude the default patterns as well if true.
+  attr_reader :apply_default_exclude
+
+  ##
+  # Words to be ignored in autolink cross-references
+  attr_accessor :autolink_excluded_words
+
+  ##
+  # 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
+
   def initialize loaded_options = nil # :nodoc:
     init_ivars
     override loaded_options if loaded_options
   end
 
+  DEFAULT_EXCLUDE = %w[
+    ~\z \.orig\z \.rej\z \.bak\z
+    \.gemspec\z
+  ]
+
   def init_ivars # :nodoc:
+    @autolink_excluded_words = []
     @dry_run = false
-    @exclude = %w[
-      ~\z \.orig\z \.rej\z \.bak\z
-      \.gemspec\z
-    ]
+    @embed_mixins = false
+    @exclude = []
     @files = nil
     @force_output = false
     @force_update = true
@@ -387,11 +420,15 @@ class RDoc::Options
     @update_output_dir = true
     @verbosity = 1
     @visibility = :protected
+    @warn_missing_rdoc_ref = true
     @webcvs = nil
     @write_options = false
     @encoding = Encoding::UTF_8
     @charset = @encoding.name
     @skip_tests = true
+    @apply_default_exclude = true
+    @class_module_path_prefix = nil
+    @file_path_prefix = nil
   end
 
   def init_with map # :nodoc:
@@ -401,6 +438,7 @@ class RDoc::Options
     @encoding = encoding ? Encoding.find(encoding) : encoding
 
     @charset        = map['charset']
+    @embed_mixins   = map['embed_mixins']
     @exclude        = map['exclude']
     @generator_name = map['generator_name']
     @hyperlink_all  = map['hyperlink_all']
@@ -417,6 +455,9 @@ class RDoc::Options
     @visibility     = map['visibility']
     @webcvs         = map['webcvs']
 
+    @apply_default_exclude   = map['apply_default_exclude']
+    @autolink_excluded_words = map['autolink_excluded_words']
+
     @rdoc_include = sanitize_path map['rdoc_include']
     @static_path  = sanitize_path map['static_path']
   end
@@ -432,6 +473,7 @@ class RDoc::Options
     end
 
     @charset        = map['charset']        if map.has_key?('charset')
+    @embed_mixins   = map['embed_mixins']   if map.has_key?('embed_mixins')
     @exclude        = map['exclude']        if map.has_key?('exclude')
     @generator_name = map['generator_name'] if map.has_key?('generator_name')
     @hyperlink_all  = map['hyperlink_all']  if map.has_key?('hyperlink_all')
@@ -448,6 +490,10 @@ class RDoc::Options
     @title          = map['title']          if map.has_key?('title')
     @visibility     = map['visibility']     if map.has_key?('visibility')
     @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')
+
+    @warn_missing_rdoc_ref = map['warn_missing_rdoc_ref'] if map.has_key?('warn_missing_rdoc_ref')
 
     if map.has_key?('rdoc_include')
       @rdoc_include = sanitize_path map['rdoc_include']
@@ -460,11 +506,12 @@ class RDoc::Options
   def == other # :nodoc:
     self.class === other and
       @encoding       == other.encoding       and
+      @embed_mixins   == other.embed_mixins   and
       @generator_name == other.generator_name and
       @hyperlink_all  == other.hyperlink_all  and
       @line_numbers   == other.line_numbers   and
       @locale         == other.locale         and
-      @locale_dir     == other.locale_dir and
+      @locale_dir     == other.locale_dir     and
       @main_page      == other.main_page      and
       @markup         == other.markup         and
       @op_dir         == other.op_dir         and
@@ -475,7 +522,9 @@ class RDoc::Options
       @template       == other.template       and
       @title          == other.title          and
       @visibility     == other.visibility     and
-      @webcvs         == other.webcvs
+      @webcvs         == other.webcvs         and
+      @apply_default_exclude == other.apply_default_exclude and
+      @autolink_excluded_words == other.autolink_excluded_words
   end
 
   ##
@@ -546,10 +595,12 @@ class RDoc::Options
     if @exclude.nil? or Regexp === @exclude then
       # done, #finish is being re-run
       @exclude
-    elsif @exclude.empty? then
+    elsif !@apply_default_exclude and @exclude.empty? then
       nil
     else
-      Regexp.new(@exclude.join("|"))
+      exclude = @exclude
+      exclude |= DEFAULT_EXCLUDE if @apply_default_exclude
+      Regexp.new(exclude.join("|"))
     end
   end
 
@@ -683,7 +734,7 @@ Usage: #{opt.program_name} [options] [names...]
 
       EOF
 
-      parsers = Hash.new { |h,parser| h[parser] = [] }
+      parsers = Hash.new { |h, parser| h[parser] = [] }
 
       RDoc::Parser.parsers.each do |regexp, parser|
         parsers[parser.name.sub('RDoc::Parser::', '')] << regexp.source
@@ -783,6 +834,11 @@ Usage: #{opt.program_name} [options] [names...]
         @exclude << value
       end
 
+      opt.on("--[no-]apply-default-exclude",
+             "Use default PATTERN to exclude.") do |value|
+        @apply_default_exclude = value
+      end
+
       opt.separator nil
 
       opt.on("--no-skipping-tests", nil,
@@ -842,6 +898,14 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
+      opt.on("--[no-]embed-mixins",
+             "Embed mixin methods, attributes, and constants",
+             "into class documentation. (default false)") do |value|
+        @embed_mixins = value
+      end
+
+      opt.separator nil
+
       markup_formats = RDoc::Text::MARKUP_FORMAT.keys.sort
 
       opt.on("--markup=MARKUP", markup_formats,
@@ -946,6 +1010,13 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
+      opt.on("--autolink-excluded-words=WORDS", Array,
+             "Words to be ignored in autolink cross-references") do |value|
+        @autolink_excluded_words.concat value
+      end
+
+      opt.separator nil
+
       opt.on("--hyperlink-all", "-A",
              "Generate hyperlinks for all words that",
              "correspond to known methods, even if they",
@@ -1087,6 +1158,13 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
+      opt.on("--warn-missing-rdoc-ref",
+             "Warn if rdoc-ref links can't be resolved") do |value|
+        @warn_missing_rdoc_ref = value
+      end
+
+      opt.separator nil
+
       opt.on("--[no-]ignore-invalid",
              "Ignore invalid options and continue",
              "(default true).") do |value|

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, file_name, content, options, stats
+  def initialize top_level, content, options, stats
     super
 
     @known_classes = RDoc::KNOWN_CLASSES.dup
@@ -248,9 +248,7 @@ class RDoc::Parser::C < RDoc::Parser
   # method that reference the same function.
 
   def add_alias(var_name, class_obj, old_name, new_name, comment)
-    al = RDoc::Alias.new '', old_name, new_name, ''
-    al.singleton = @singleton_classes.key? var_name
-    al.comment = comment
+    al = RDoc::Alias.new '', old_name, new_name, comment, singleton: @singleton_classes.key?(var_name)
     al.record_location @top_level
     class_obj.add_alias al
     @stats.add_alias al
@@ -405,6 +403,7 @@ class RDoc::Parser::C < RDoc::Parser
                  \s*(.*?)\s*\)\s*;
                  %xm) do |type, var_name, const_name, definition|
       var_name = "rb_cObject" if !var_name or var_name == "rb_mKernel"
+      type = "const" if type == "global_const"
       handle_constants type, var_name, const_name, definition
     end
 
@@ -440,7 +439,7 @@ class RDoc::Parser::C < RDoc::Parser
   # Scans #content for rb_include_module
 
   def do_includes
-    @content.scan(/rb_include_module\s*\(\s*(\w+?),\s*(\w+?)\s*\)/) do |c,m|
+    @content.scan(/rb_include_module\s*\(\s*(\w+?),\s*(\w+?)\s*\)/) do |c, m|
       next unless cls = @classes[c]
       m = @known_classes[m] || m
 
@@ -760,6 +759,10 @@ class RDoc::Parser::C < RDoc::Parser
         rb_define_(?<type>\w+)\(\s*(?:\w+),\s*
                            "(?<name>\w+)"\s*,
                            .*?\)\s*;
+    | (?<doc>(?>^\s*/\*.*?\*/\s+))
+        rb_define_global_(?<type>const)\(\s*
+                           "(?<name>\w+)"\s*,
+                           .*?\)\s*;
     |  (?<doc>(?>^\s*/\*.*?\*/\s+))
         rb_file_(?<type>const)\(\s*
                            "(?<name>\w+)"\s*,
@@ -805,7 +808,7 @@ class RDoc::Parser::C < RDoc::Parser
 
   def find_modifiers comment, meth_obj
     comment.normalize
-    comment.extract_call_seq meth_obj
+    meth_obj.call_seq = comment.extract_call_seq
 
     look_for_directives_in meth_obj, comment
   end
@@ -1010,10 +1013,9 @@ class RDoc::Parser::C < RDoc::Parser
         type = 'method' # force public
       end
 
-      meth_obj = RDoc::AnyMethod.new '', meth_name
+      singleton = singleton || %w[singleton_method module_function].include?(type)
+      meth_obj = RDoc::AnyMethod.new '', meth_name, singleton: singleton
       meth_obj.c_function = function
-      meth_obj.singleton =
-        singleton || %w[singleton_method module_function].include?(type)
 
       p_count = Integer(param_count) rescue -1
 
@@ -1097,15 +1099,34 @@ 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

data/lib/rdoc/parser/changelog.rb

@@ -193,7 +193,7 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
 
     entries << [entry_name, entry_body] if entry_name
 
-    entries.reject! do |(entry,_)|
+    entries.reject! do |(entry, _)|
       entry == nil
     end
 
@@ -210,8 +210,9 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
     grouped_entries = group_entries entries
 
     doc = create_document grouped_entries
-
-    @top_level.comment = doc
+    comment = RDoc::Comment.new(@content)
+    comment.document = doc
+    @top_level.comment = comment
 
     @top_level
   end
@@ -221,7 +222,7 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
 
   module Git
     ##
-    # Parses auxiliary info.  Currentry `base-url` to expand
+    # Parses auxiliary info.  Currently `base-url` to expand
     # references is effective.
 
     def parse_info(info)