rdoc 6.14.2 → 6.16.1

data/lib/rdoc/markup/pre_process.rb

@@ -97,18 +97,15 @@ class RDoc::Markup::PreProcess
   # RDoc::CodeObject#metadata for details.
 
   def handle(text, code_object = nil, &block)
-    first_line = 1
     if RDoc::Comment === text then
       comment = text
       text = text.text
-      first_line = comment.line || 1
     end
 
     # regexp helper (square brackets for optional)
     # $1      $2  $3        $4      $5
     # [prefix][\]:directive:[spaces][param]newline
-    text = text.lines.map.with_index(first_line) do |line, num|
-      next line unless line =~ /\A([ \t]*(?:#|\/?\*)?[ \t]*)(\\?):([\w-]+):([ \t]*)(.+)?(\r?\n|$)/
+    text = text.gsub(/^([ \t]*(?:#|\/?\*)?[ \t]*)(\\?):([\w-]+):([ \t]*)(.+)?(\r?\n|$)/) do
       # skip something like ':toto::'
       next $& if $4.empty? and $5 and $5[0, 1] == ':'
 
@@ -122,9 +119,8 @@ class RDoc::Markup::PreProcess
         comment.format = $5.downcase
         next "#{$1.strip}\n"
       end
-
-      handle_directive $1, $3, $5, code_object, text.encoding, num, &block
-    end.join
+      handle_directive $1, $3, $5, code_object, text.encoding, &block
+    end
 
     if comment then
       comment.text = text
@@ -132,11 +128,39 @@ class RDoc::Markup::PreProcess
       comment = text
     end
 
+    run_post_processes(comment, code_object)
+
+    text
+  end
+
+  # Apply directives to a code object
+
+  def run_pre_processes(comment_text, code_object, start_line_no, type)
+    comment_text, directives = parse_comment(comment_text, start_line_no, type)
+    directives.each do |directive, (param, line_no)|
+      handle_directive('', directive, param, code_object)
+    end
+    if code_object.is_a?(RDoc::AnyMethod) && (call_seq, = directives['call-seq']) && call_seq
+      code_object.call_seq = call_seq.lines.map(&:chomp).reject(&:empty?).join("\n")
+    end
+    format, = directives['markup']
+    [comment_text, format]
+  end
+
+  # Perform post preocesses to a code object
+
+  def run_post_processes(comment, code_object)
     self.class.post_processors.each do |handler|
       handler.call comment, code_object
     end
+  end
 
-    text
+  # Parse comment and return [normalized_comment_text, directives_hash]
+
+  def parse_comment(text, line_no, type)
+    RDoc::Comment.parse(text, @input_file_name, line_no, type) do |filename, prefix_indent|
+      include_file(filename, prefix_indent, text.encoding)
+    end
   end
 
   ##
@@ -151,7 +175,7 @@ class RDoc::Markup::PreProcess
   # When 1.8.7 support is ditched prefix can be defaulted to ''
 
   def handle_directive(prefix, directive, param, code_object = nil,
-                       encoding = nil, line = nil)
+                       encoding = nil)
     blankline = "#{prefix.strip}\n"
     directive = directive.downcase
 
@@ -244,7 +268,7 @@ class RDoc::Markup::PreProcess
 
       blankline
     else
-      result = yield directive, param, line if block_given?
+      result = yield directive, param if block_given?
 
       case result
       when nil then

data/lib/rdoc/markup/to_html.rb

@@ -158,19 +158,16 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   def handle_regexp_TIDYLINK(target)
     text = target.text
 
-    return text unless
-      text =~ /^\{(.*)\}\[(.*?)\]$/ or text =~ /^(\S+)\[(.*?)\]$/
-
-    label = $1
-    url   = CGI.escapeHTML($2)
+    if tidy_link_capturing?
+      return finish_tidy_link(text)
+    end
 
-    if /^rdoc-image:/ =~ label
-      label = handle_RDOCLINK(label)
-    else
-      label = CGI.escapeHTML(label)
+    if text.start_with?('{') && !text.include?('}')
+      start_tidy_link text
+      return ''
     end
 
-    gen_url url, label
+    convert_complete_tidy_link(text)
   end
 
   # :section: Visitor
@@ -315,11 +312,13 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
             else
               "\n<h#{level}>"
             end
-    @res << to_html(heading.text)
-    unless @options.pipe then
-      @res << "<span><a href=\"##{label}\">&para;</a>"
-      @res << " <a href=\"#top\">&uarr;</a></span>"
+
+    if @options.pipe
+      @res << to_html(heading.text)
+    else
+      @res << "<a href=\"##{label}\">#{to_html(heading.text)}</a>"
     end
+
     @res << "</h#{level}>\n"
   end
 
@@ -458,4 +457,153 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     super convert_flow @am.flow item
   end
 
+  private
+
+  def convert_flow(flow_items)
+    res = []
+
+    flow_items.each do |item|
+      case item
+      when String
+        append_flow_fragment res, convert_string(item)
+      when RDoc::Markup::AttrChanger
+        off_tags res, item
+        on_tags  res, item
+      when RDoc::Markup::RegexpHandling
+        append_flow_fragment res, convert_regexp_handling(item)
+      else
+        raise "Unknown flow element: #{item.inspect}"
+      end
+    end
+
+    res.join
+  end
+
+  def append_flow_fragment(res, fragment)
+    return if fragment.nil? || fragment.empty?
+
+    emit_tidy_link_fragment(res, fragment)
+  end
+
+  def append_to_tidy_label(fragment)
+    @tidy_link_buffer << fragment
+  end
+
+  ##
+  # Matches an entire tidy link with a braced label "{label}[url]".
+  #
+  # Capture 1: label contents.
+  # Capture 2: URL text.
+  # Capture 3: trailing content.
+  TIDY_LINK_WITH_BRACES = /\A\{(.*?)\}\[(.*?)\](.*)\z/
+
+  ##
+  # Matches the tail of a braced tidy link when the opening brace was
+  # consumed earlier while accumulating the label text.
+  #
+  # Capture 1: remaining label content.
+  # Capture 2: URL text.
+  # Capture 3: trailing content.
+  TIDY_LINK_WITH_BRACES_TAIL = /\A(.*?)\}\[(.*?)\](.*)\z/
+
+  ##
+  # Matches a tidy link with a single-word label "label[url]".
+  #
+  # Capture 1: the single-word label (no whitespace).
+  # Capture 2: URL text between the brackets.
+  TIDY_LINK_SINGLE_WORD = /\A(\S+)\[(.*?)\](.*)\z/
+
+  def convert_complete_tidy_link(text)
+    return text unless
+      text =~ TIDY_LINK_WITH_BRACES or text =~ TIDY_LINK_SINGLE_WORD
+
+    label = $1
+    url   = CGI.escapeHTML($2)
+
+    label_html = if /^rdoc-image:/ =~ label
+                   handle_RDOCLINK(label)
+                 else
+                   render_tidy_link_label(label)
+                 end
+
+    gen_url url, label_html
+  end
+
+  def emit_tidy_link_fragment(res, fragment)
+    if tidy_link_capturing?
+      append_to_tidy_label fragment
+    else
+      res << fragment
+    end
+  end
+
+  def finish_tidy_link(text)
+    label_tail, url, trailing = extract_tidy_link_parts(text)
+    append_to_tidy_label CGI.escapeHTML(label_tail) unless label_tail.empty?
+
+    return '' unless url
+
+    label_html = @tidy_link_buffer
+    @tidy_link_buffer = nil
+    link = gen_url(url, label_html)
+
+    return link if trailing.empty?
+
+    link + CGI.escapeHTML(trailing)
+  end
+
+  def extract_tidy_link_parts(text)
+    if text =~ TIDY_LINK_WITH_BRACES
+      [$1, CGI.escapeHTML($2), $3]
+    elsif text =~ TIDY_LINK_WITH_BRACES_TAIL
+      [$1, CGI.escapeHTML($2), $3]
+    elsif text =~ TIDY_LINK_SINGLE_WORD
+      [$1, CGI.escapeHTML($2), $3]
+    else
+      [text, nil, '']
+    end
+  end
+
+  def on_tags(res, item)
+    each_attr_tag(item.turn_on) do |tag|
+      emit_tidy_link_fragment(res, annotate(tag.on))
+      @in_tt += 1 if tt? tag
+    end
+  end
+
+  def off_tags(res, item)
+    each_attr_tag(item.turn_off, true) do |tag|
+      emit_tidy_link_fragment(res, annotate(tag.off))
+      @in_tt -= 1 if tt? tag
+    end
+  end
+
+  def start_tidy_link(text)
+    @tidy_link_buffer = String.new
+    append_to_tidy_label CGI.escapeHTML(text.delete_prefix('{'))
+  end
+
+  def tidy_link_capturing?
+    !!@tidy_link_buffer
+  end
+
+  def render_tidy_link_label(label)
+    RDoc::Markup::LinkLabelToHtml.render(label, @options, @from_path)
+  end
+end
+
+##
+# Formatter dedicated to rendering tidy link labels without mutating the
+# calling formatter's state.
+
+class RDoc::Markup::LinkLabelToHtml < RDoc::Markup::ToHtml
+  def self.render(label, options, from_path)
+    new(options, from_path).to_html(label)
+  end
+
+  def initialize(options, from_path = nil)
+    super(options)
+
+    self.from_path = from_path if from_path
+  end
 end

data/lib/rdoc/markup/to_html_crossref.rb

@@ -184,38 +184,35 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
     end
   end
 
-  def convert_flow(flow)
+  def convert_flow(flow_items, &block)
     res = []
 
     i = 0
-    while i < flow.size
-      item = flow[i]
-      i += 1
+    while i < flow_items.size
+      item = flow_items[i]
+
       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
+      when RDoc::Markup::AttrChanger
+        if !tidy_link_capturing? && (text = convert_tt_crossref(flow_items, i))
+          text = block.call(text, res) if block
+          append_flow_fragment res, text
+          i += 3
           next
         end
+
         off_tags res, item
-        on_tags res, item
-      when String then
+        on_tags  res, item
+        i += 1
+      when String
         text = convert_string(item)
-        text = yield text, res if defined?(yield)
-        res << text
-      when RDoc::Markup::RegexpHandling then
+        text = block.call(text, res) if block
+        append_flow_fragment res, text
+        i += 1
+      when RDoc::Markup::RegexpHandling
         text = convert_regexp_handling(item)
-        text = yield text, res if defined?(yield)
-        res << text
+        text = block.call(text, res) if block
+        append_flow_fragment res, text
+        i += 1
       else
         raise "Unknown flow element: #{item.inspect}"
       end
@@ -223,4 +220,37 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
 
     res.join('')
   end
+
+  private
+
+  ##
+  # Detects <tt>...</tt> spans that contain a single cross-reference candidate.
+  # When the candidate occupies the whole span (aside from trailing
+  # punctuation), the tt markup is replaced by the resolved cross-reference.
+
+  def convert_tt_crossref(flow_items, index)
+    opener = flow_items[index]
+    return unless tt_tag?(opener.turn_on)
+
+    string = flow_items[index + 1]
+    closer = flow_items[index + 2]
+
+    return unless String === string
+    return unless RDoc::Markup::AttrChanger === closer
+    return unless tt_tag?(closer.turn_off, true)
+
+    crossref_regexp = @options.hyperlink_all ? ALL_CROSSREF_REGEXP : CROSSREF_REGEXP
+    match = crossref_regexp.match(string)
+    return unless match
+    return unless match.begin(1).zero?
+
+    trailing = match.post_match
+    # Only convert when the remainder is punctuation/whitespace so other tt text stays literal.
+    return unless trailing.match?(/\A[[:punct:]\s]*\z/)
+
+    text = cross_reference(string)
+    return if text == string
+
+    text
+  end
 end

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
 
@@ -378,6 +378,21 @@ class RDoc::Options
 
   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
@@ -396,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
@@ -435,6 +449,7 @@ class RDoc::Options
     @class_module_path_prefix = nil
     @file_path_prefix = nil
     @canonical_root = nil
+    @footer_content = nil
   end
 
   def init_with(map) # :nodoc:
@@ -463,6 +478,7 @@ 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']
@@ -499,6 +515,7 @@ class RDoc::Options
     @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')
 
@@ -1213,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 = []
 
@@ -1233,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

data/lib/rdoc/parser/c.rb

@@ -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
 
@@ -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
 
@@ -807,9 +801,6 @@ 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
-
     look_for_directives_in meth_obj, comment
   end
 
@@ -823,10 +814,10 @@ class RDoc::Parser::C < RDoc::Parser
     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
@@ -1061,10 +1052,13 @@ 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
+    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
 
   ##
@@ -1102,35 +1096,10 @@ class RDoc::Parser::C < RDoc::Parser
   # 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
-
+    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