rdoc 7.1.0 → 8.0.0

data/lib/rdoc/markup/to_markdown.rb

@@ -9,7 +9,7 @@ class RDoc::Markup::ToMarkdown < RDoc::Markup::ToRdoc
   ##
   # Creates a new formatter that will output Markdown format text
 
-  def initialize(markup = nil)
+  def initialize
     super
 
     @headings[1] = ['# ',      '']
@@ -20,27 +20,10 @@ class RDoc::Markup::ToMarkdown < RDoc::Markup::ToRdoc
     @headings[6] = ['###### ', '']
 
     add_regexp_handling_RDOCLINK
-    add_regexp_handling_TIDYLINK
 
     @hard_break = "  \n"
   end
 
-  ##
-  # Maps attributes to HTML sequences
-
-  def init_tags
-    add_tag :BOLD, '**', '**'
-    add_tag :EM,   '*',  '*'
-    add_tag :TT,   '`',  '`'
-  end
-
-  ##
-  # Adds a newline to the output
-
-  def handle_regexp_HARD_BREAK(target)
-    "  \n"
-  end
-
   ##
   # Finishes consumption of `list`
 
@@ -94,6 +77,65 @@ class RDoc::Markup::ToMarkdown < RDoc::Markup::ToRdoc
     end
   end
 
+  def add_tag(tag, simple_tag, content)
+    if content.match?(/\A[\w\s]+\z/)
+      emit_inline("#{simple_tag}#{content}#{simple_tag}")
+    else
+      emit_inline("<#{tag}>#{content}</#{tag}>")
+    end
+  end
+
+  def handle_tag(nodes, simple_tag, tag)
+    if nodes.size == 1 && String === nodes[0]
+      content = apply_regexp_handling(nodes[0]).map do |text, converted|
+        converted ? text : convert_string(text)
+      end.join
+      add_tag(tag, simple_tag, content)
+    else
+      emit_inline("<#{tag}>")
+      traverse_inline_nodes(nodes)
+      emit_inline("</#{tag}>")
+    end
+  end
+
+  def handle_TIDYLINK(label_part, url)
+    if url =~ /^rdoc-label:foot/ then
+      emit_inline(handle_rdoc_link(url))
+    else
+      emit_inline('[')
+      traverse_inline_nodes(label_part)
+      emit_inline("](#{url})")
+    end
+  end
+
+  def handle_BOLD(nodes)
+    handle_tag(nodes, '**', 'strong')
+  end
+
+  def handle_EM(nodes)
+    handle_tag(nodes, '*', 'em')
+  end
+
+  def handle_BOLD_WORD(word)
+    add_tag('strong', '**', convert_string(word))
+  end
+
+  def handle_EM_WORD(word)
+    add_tag('em', '*', convert_string(word))
+  end
+
+  def handle_TT(text)
+    add_tag('code', '`', convert_string(text))
+  end
+
+  def handle_STRIKE(nodes)
+    handle_tag(nodes, '~~', 's')
+  end
+
+  def handle_HARD_BREAK
+    emit_inline("  \n")
+  end
+
   ##
   # Prepares the visitor for consuming `list`
 
@@ -163,29 +205,11 @@ class RDoc::Markup::ToMarkdown < RDoc::Markup::ToRdoc
     end
   end
 
-  ##
-  # Converts the RDoc markup tidylink into a Markdown.style link.
-
-  def handle_regexp_TIDYLINK(target)
-    text = target.text
-
-    return text unless text =~ /\{(.*?)\}\[(.*?)\]/ or text =~ /(\S+)\[(.*?)\]/
-
-    label = $1
-    url   = $2
-
-    if url =~ /^rdoc-label:foot/ then
-      handle_rdoc_link url
-    else
-      gen_url url, label
-    end
-  end
-
   ##
   # Converts the rdoc-...: links into a Markdown.style links.
 
-  def handle_regexp_RDOCLINK(target)
-    handle_rdoc_link target.text
+  def handle_regexp_RDOCLINK(text)
+    handle_rdoc_link text
   end
 
 end

data/lib/rdoc/markup/to_rdoc.rb

@@ -52,26 +52,16 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
   ##
   # Creates a new formatter that will output (mostly) \RDoc markup
 
-  def initialize(markup = nil)
-    super nil, markup
+  def initialize
+    super
 
     @markup.add_regexp_handling(/\\\S/, :SUPPRESSED_CROSSREF)
     @width = 78
-    init_tags
 
     @headings = DEFAULT_HEADINGS.dup
     @hard_break = "\n"
   end
 
-  ##
-  # Maps attributes to HTML sequences
-
-  def init_tags
-    add_tag :BOLD, "<b>", "</b>"
-    add_tag :TT,   "<tt>", "</tt>"
-    add_tag :EM,   "<em>", "</em>"
-  end
-
   ##
   # Adds +blank_line+ to the output
 
@@ -253,7 +243,7 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
     header = header.map { |h| attributes h }
     body = body.map { |row| row.map { |t| attributes t } }
     widths = header.zip(*body).map do |cols|
-      cols.map { |col| calculate_text_width(col) }.max
+      cols.compact.map { |col| calculate_text_width(col) }.max
     end
     aligns = aligns.map do |a|
       case a
@@ -271,7 +261,8 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
     end.join("|").rstrip << "\n"
     @res << widths.map {|w| "-" * w }.join("|") << "\n"
     body.each do |row|
-      @res << row.zip(widths, aligns).map do |t, w, a|
+      @res << widths.zip(aligns).each_with_index.map do |(w, a), i|
+        t = row[i] || ""
         extra_width = t.size - calculate_text_width(t)
         t.__send__(a, w + extra_width)
       end.join("|").rstrip << "\n"
@@ -282,12 +273,90 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
     text.size
   end
 
+  def handle_PLAIN_TEXT(text)
+    add_text(text)
+  end
+
+  def handle_REGEXP_HANDLING_TEXT(text)
+    add_text(text)
+  end
+
+  def handle_BOLD(target)
+    on(:BOLD)
+    super
+    off(:BOLD)
+  end
+
+  def handle_EM(target)
+    on(:EM)
+    super
+    off(:EM)
+  end
+
+  def handle_BOLD_WORD(word)
+    on(:BOLD)
+    super
+    off(:BOLD)
+  end
+
+  def handle_EM_WORD(word)
+    on(:EM)
+    super
+    off(:EM)
+  end
+
+  def handle_TT(code)
+    on(:TT)
+    super
+    off(:TT)
+  end
+
+  def handle_STRIKE(target)
+    on(:STRIKE)
+    super
+    off(:STRIKE)
+  end
+
+  def handle_HARD_BREAK
+    add_text("\n")
+  end
+
+  def handle_TIDYLINK(label_part, url)
+    super
+    add_text("( #{url} )")
+  end
+
+  def handle_inline(text, initial_attributes = [])
+    @attributes = Hash.new(0)
+    initial_attributes.each { |attr| on(attr) }
+    out = @inline_output = +''
+    super(text)
+    @inline_output = nil
+    out
+  end
+
+  def on(attr)
+    @attributes[attr] += 1
+  end
+
+  def off(attr)
+    @attributes[attr] -= 1
+    @attributes.delete(attr) if @attributes[attr] == 0
+  end
+
+  def add_text(text)
+    emit_inline(text)
+  end
+
+  def emit_inline(text)
+    @inline_output << text
+  end
+
   ##
-  # Applies attribute-specific markup to +text+ using RDoc::AttributeManager
+  # Applies attribute-specific markup to +text+ using RDoc::Markup::InlineParser
 
   def attributes(text)
-    flow = @am.flow text.dup
-    convert_flow flow
+    handle_inline(text)
   end
 
   ##
@@ -300,17 +369,8 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
   ##
   # Removes preceding \\ from the suppressed crossref +target+
 
-  def handle_regexp_SUPPRESSED_CROSSREF(target)
-    text = target.text
-    text = text.sub('\\', '') unless in_tt?
-    text
-  end
-
-  ##
-  # Adds a newline to the output
-
-  def handle_regexp_HARD_BREAK(target)
-    "\n"
+  def handle_regexp_SUPPRESSED_CROSSREF(text)
+    text.sub('\\', '')
   end
 
   ##

data/lib/rdoc/markup/to_table_of_contents.rb

@@ -25,7 +25,7 @@ class RDoc::Markup::ToTableOfContents < RDoc::Markup::Formatter
   attr_accessor :omit_headings_below
 
   def initialize # :nodoc:
-    super nil
+    super
 
     @omit_headings_below = nil
   end

data/lib/rdoc/markup/to_test.rb

@@ -18,8 +18,16 @@ class RDoc::Markup::ToTest < RDoc::Markup::Formatter
     @res
   end
 
+  def handle_PLAIN_TEXT(text)
+    @res << text
+  end
+
+  def handle_REGEXP_HANDLING_TEXT(text)
+    @res << text
+  end
+
   def accept_paragraph(paragraph)
-    @res << convert_flow(@am.flow(paragraph.text))
+    handle_inline(paragraph.text)
   end
 
   def accept_raw(raw)

data/lib/rdoc/markup/to_tt_only.rb

@@ -15,15 +15,6 @@ class RDoc::Markup::ToTtOnly < RDoc::Markup::Formatter
 
   attr_reader :res
 
-  ##
-  # Creates a new tt-only formatter.
-
-  def initialize(markup = nil)
-    super nil, markup
-
-    add_tag :TT, nil, nil
-  end
-
   ##
   # Adds tts from +block_quote+ to the output
 
@@ -82,22 +73,18 @@ class RDoc::Markup::ToTtOnly < RDoc::Markup::Formatter
   # Extracts tt sections from +text+
 
   def tt_sections(text)
-    flow = @am.flow text.dup
-
-    flow.each do |item|
-      case item
-      when String then
-        @res << item if in_tt?
-      when RDoc::Markup::AttrChanger then
-        off_tags res, item
-        on_tags res, item
-      when RDoc::Markup::RegexpHandling then
-        @res << convert_regexp_handling(item) if in_tt? # TODO can this happen?
+    parsed = RDoc::Markup::InlineParser.new(text).parse
+    traverse = -> node {
+      next if String === node
+      if node[:type] == :TT
+        res << nil
+        res << node[:children][0] || ''
+        res << nil
       else
-        raise "Unknown flow element: #{item.inspect}"
+        node[:children].each(&traverse)
       end
-    end
-
+    }
+    parsed.each(&traverse)
     res
   end
 

data/lib/rdoc/markup/verbatim.rb

@@ -9,7 +9,7 @@ class RDoc::Markup::Verbatim < RDoc::Markup::Raw
 
   attr_accessor :format
 
-  def initialize *parts # :nodoc:
+  def initialize(*parts) # :nodoc:
     super
 
     @format = nil

data/lib/rdoc/markup.rb

@@ -79,7 +79,7 @@
 #
 #   class WikiHtml < RDoc::Markup::ToHtml
 #     def handle_regexp_WIKIWORD(target)
-#       "<font color=red>" + target.text + "</font>"
+#       "<font color=red>" + target + "</font>"
 #     end
 #   end
 #
@@ -110,10 +110,10 @@
 
 class RDoc::Markup
 
-  ##
-  # An AttributeManager which handles inline markup.
+  # Array of regexp handling pattern and its name. A regexp handling
+  # sequence is something like a WikiWord
 
-  attr_reader :attribute_manager
+  attr_reader :regexp_handlings
 
   ##
   # Parses +str+ into an RDoc::Markup::Document.
@@ -148,27 +148,11 @@ https://github.com/ruby/rdoc/issues
   # structure (paragraphs, lists, and so on).  Invoke an event handler as we
   # identify significant chunks.
 
-  def initialize(attribute_manager = nil)
-    @attribute_manager = attribute_manager || RDoc::Markup::AttributeManager.new
+  def initialize
+    @regexp_handlings = []
     @output = nil
   end
 
-  ##
-  # Add to the sequences used to add formatting to an individual word (such
-  # as *bold*).  Matching entries will generate attributes that the output
-  # formatters can recognize by their +name+.
-
-  def add_word_pair(start, stop, name)
-    @attribute_manager.add_word_pair(start, stop, name)
-  end
-
-  ##
-  # Add to the sequences recognized as general markup.
-
-  def add_html(tag, name)
-    @attribute_manager.add_html(tag, name)
-  end
-
   ##
   # Add to other inline sequences.  For example, we could add WikiWords using
   # something like:
@@ -178,7 +162,7 @@ https://github.com/ruby/rdoc/issues
   # Each wiki word will be presented to the output formatter.
 
   def add_regexp_handling(pattern, name)
-    @attribute_manager.add_regexp_handling(pattern, name)
+    @regexp_handlings << [pattern, name]
   end
 
   ##
@@ -197,15 +181,9 @@ https://github.com/ruby/rdoc/issues
   end
 
   autoload :Parser,                "#{__dir__}/markup/parser"
+  autoload :InlineParser,          "#{__dir__}/markup/inline_parser"
   autoload :PreProcess,            "#{__dir__}/markup/pre_process"
 
-  # Inline markup classes
-  autoload :AttrChanger,           "#{__dir__}/markup/attr_changer"
-  autoload :AttrSpan,              "#{__dir__}/markup/attr_span"
-  autoload :Attributes,            "#{__dir__}/markup/attributes"
-  autoload :AttributeManager,      "#{__dir__}/markup/attribute_manager"
-  autoload :RegexpHandling,        "#{__dir__}/markup/regexp_handling"
-
   # RDoc::Markup AST
   autoload :BlankLine,             "#{__dir__}/markup/blank_line"
   autoload :BlockQuote,            "#{__dir__}/markup/block_quote"

data/lib/rdoc/options.rb

@@ -74,23 +74,6 @@ require 'pathname'
 
 class RDoc::Options
 
-  ##
-  # The deprecated options.
-
-  DEPRECATED = {
-    '--accessor'      => 'support discontinued',
-    '--diagram'       => 'support discontinued',
-    '--help-output'   => 'support discontinued',
-    '--image-format'  => 'was an option for --diagram',
-    '--inline-source' => 'source code is now always inlined',
-    '--merge'         => 'ri now always merges class information',
-    '--one-file'      => 'support discontinued',
-    '--op-name'       => 'support discontinued',
-    '--opname'        => 'support discontinued',
-    '--promiscuous'   => 'files always only document their content',
-    '--ri-system'     => 'Ruby installers use other techniques',
-  }
-
   ##
   # RDoc options ignored (or handled specially) by --write-options
 
@@ -112,8 +95,8 @@ class RDoc::Options
     pipe
     rdoc_include
     root
+    server_port
     static_path
-    stylesheet_url
     template
     template_dir
     update_output_dir
@@ -346,6 +329,13 @@ class RDoc::Options
 
   attr_reader :visibility
 
+  ##
+  # When set to a port number, starts a live-reloading server instead of
+  # writing files.  Defaults to +false+ (no server).  Set via
+  # <tt>--server[=PORT]</tt>.
+
+  attr_reader :server_port
+
   ##
   # Indicates if files of test suites should be skipped
   attr_accessor :skip_tests
@@ -428,9 +418,9 @@ class RDoc::Options
     @output_decoration = true
     @rdoc_include = []
     @root = Pathname(Dir.pwd)
+    @server_port = false
     @show_hash = false
     @static_path = []
-    @stylesheet_url = nil # TODO remove in RDoc 4
     @tab_width = 8
     @template = nil
     @template_dir = nil
@@ -609,7 +599,12 @@ class RDoc::Options
     ivars.sort.each do |ivar|
       yaml[ivar] = instance_variable_get("@#{ivar}")
     end
-    yaml.to_yaml
+
+    if yaml.respond_to?(:to_yaml)
+      yaml.to_yaml
+    else
+      RDoc.yaml_serializer.dump(yaml)
+    end
   end
 
   ##
@@ -769,14 +764,6 @@ Usage: #{opt.program_name} [options] [names...]
       end
       opt.banner += "  - TomDoc:  Only in ruby files\n"
 
-      opt.banner += "\n  The following options are deprecated:\n\n"
-
-      name_length = DEPRECATED.keys.sort_by { |k| k.length }.last.length
-
-      DEPRECATED.sort_by { |k,| k }.each do |name, reason|
-        opt.banner += "    %*1$2$s  %3$s\n" % [-name_length, name, reason]
-      end
-
       opt.accept Template do |template|
         template_dir = template_dir_for template
 
@@ -913,7 +900,7 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
-      opt.on("--visibility=VISIBILITY", "-V", RDoc::VISIBILITIES + [:nodoc],
+      opt.on("--visibility=VISIBILITY", RDoc::VISIBILITIES + [:nodoc],
              "Minimum visibility to document a method.",
              "One of 'public', 'protected' (the default),",
              "'private' or 'nodoc' (show everything)") do |value|
@@ -1013,14 +1000,6 @@ Usage: #{opt.program_name} [options] [names...]
         @op_dir = value
       end
 
-      opt.separator nil
-
-      opt.on("-d",
-             "Deprecated --diagram option.",
-             "Prevents firing debug mode",
-             "with legacy invocation.") do |value|
-      end
-
       opt.separator nil
       opt.separator 'HTML generator options:'
       opt.separator nil
@@ -1158,6 +1137,15 @@ Usage: #{opt.program_name} [options] [names...]
       opt.separator "Generic options:"
       opt.separator nil
 
+      opt.on("--server[=PORT]", Integer,
+             "Start a web server to preview",
+             "documentation with live reload.",
+             "Defaults to port 4000.") do |port|
+        @server_port = port || 4000
+      end
+
+      opt.separator nil
+
       opt.on("--write-options",
              "Write .rdoc_options to the current",
              "directory with the given options.  Not all",
@@ -1230,15 +1218,12 @@ Usage: #{opt.program_name} [options] [names...]
       opt.separator nil
     end
 
-    deprecated = []
     invalid = []
 
     begin
       opts.parse! argv
     rescue OptionParser::ParseError => e
-      if DEPRECATED[e.args.first] then
-        deprecated << e.args.first
-      elsif %w[--format --ri -r --ri-site -R].include? e.args.first then
+      if %w[--format --ri -r --ri-site -R].include? e.args.first then
         raise
       else
         invalid << e.args.join(' ')
@@ -1254,12 +1239,6 @@ Usage: #{opt.program_name} [options] [names...]
       invalid << '-p (with files)'
     end
 
-    unless quiet then
-      deprecated.each do |opt|
-        $stderr.puts 'option ' + opt + ' is deprecated: ' + DEPRECATED[opt]
-      end
-    end
-
     unless invalid.empty? then
       invalid = "invalid options: #{invalid.join ', '}"
 
@@ -1405,10 +1384,16 @@ Usage: #{opt.program_name} [options] [names...]
 
     RDoc.load_yaml
 
-    begin
-      options = YAML.safe_load File.read('.rdoc_options'), permitted_classes: [RDoc::Options, Symbol]
-    rescue Psych::SyntaxError
-      raise RDoc::Error, "#{options_file} is not a valid rdoc options file"
+    content = File.read('.rdoc_options')
+
+    if defined?(Psych)
+      begin
+        options = Psych.safe_load content, permitted_classes: [RDoc::Options, Symbol]
+      rescue Psych::SyntaxError
+        raise RDoc::Error, "#{options_file} is not a valid rdoc options file"
+      end
+    else
+      options = RDoc.yaml_serializer.load(content)
     end
 
     return RDoc::Options.new unless options # Allow empty file.

data/lib/rdoc/parser/c.rb

@@ -248,7 +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, comment, singleton: @singleton_classes.key?(var_name)
+    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
@@ -683,6 +683,7 @@ class RDoc::Parser::C < RDoc::Parser
       container.name = base_name if base_name
 
       container.record_location @top_level
+      @top_level.add_to_classes_or_modules container
       @classes[raw_name] = container
     end
     @classes[raw_name]
@@ -847,7 +848,7 @@ class RDoc::Parser::C < RDoc::Parser
 
     name = attr_name.gsub(/rb_intern(?:_const)?\("([^"]+)"\)/, '\1')
 
-    attr = RDoc::Attr.new '', name, rw, comment
+    attr = RDoc::Attr.new name, rw, comment
 
     attr.record_location @top_level
     class_obj.add_attribute attr
@@ -898,6 +899,7 @@ class RDoc::Parser::C < RDoc::Parser
     end
 
     cm.record_location enclosure.top_level
+    enclosure.top_level.add_to_classes_or_modules cm
 
     find_class_comment cm.full_name, cm
 
@@ -1005,7 +1007,7 @@ class RDoc::Parser::C < RDoc::Parser
       end
 
       singleton = singleton || %w[singleton_method module_function].include?(type)
-      meth_obj = RDoc::AnyMethod.new '', meth_name, singleton: singleton
+      meth_obj = RDoc::AnyMethod.new meth_name, singleton: singleton
       meth_obj.c_function = function
 
       p_count = Integer(param_count) rescue -1
@@ -1014,7 +1016,7 @@ class RDoc::Parser::C < RDoc::Parser
         file_name = File.join @file_dir, source_file
 
         if File.exist? file_name then
-          file_content = File.read file_name
+          file_content = RDoc::Encoding.read_file file_name, @options.encoding
         else
           @options.warn "unknown source #{source_file} for #{meth_name} in #{@file_name}"
         end
@@ -1089,11 +1091,10 @@ class RDoc::Parser::C < RDoc::Parser
   # Look for directives in a normal comment block:
   #
   #   /*
-  #    * :title: My Awesome Project
+  #    * :nodoc:
   #    */
   #
   # 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)
     comment.text, format = @preprocess.run_pre_processes(comment.text, context, comment.line || 1, :c)