rdoc 6.17.0 → 8.1.0

data/lib/rdoc/version.rb

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

data/lib/rdoc.rb

@@ -100,7 +100,14 @@ module RDoc
     %w[arg args yield yields notnew not-new not_new doc]
 
   ##
-  # Loads the best available YAML library.
+  # Loads the YAML backend used for <tt>.rdoc_options</tt>.
+  #
+  # Psych is preferred and used whenever it can be required. Requiring +yaml+
+  # is not attempted as a fallback because +yaml+ is merely a thin wrapper that
+  # loads Psych anyway. When Psych is genuinely unavailable, a minimal
+  # serializer shipped with RubyGems or Bundler is loaded instead, so that RDoc
+  # does not need a runtime dependency on Psych. Callers branch on whether
+  # Psych is defined and use ::yaml_serializer otherwise.
 
   def self.load_yaml
     begin
@@ -113,11 +120,25 @@ module RDoc
     begin
       require 'psych'
     rescue ::LoadError
-    ensure
-      require 'yaml'
+      # Psych is unavailable; load the stub serializer shipped with RubyGems,
+      # or Bundler's copy on RubyGems older than 3.5 (Ruby 3.2) where
+      # rubygems/yaml_serializer does not exist yet.
+      begin
+        require 'rubygems/yaml_serializer'
+      rescue ::LoadError
+        require 'bundler/yaml_serializer'
+      end
     end
   end
 
+  ##
+  # The minimal YAML serializer module loaded by ::load_yaml as a fallback.
+  # Only meaningful when Psych is not defined.
+
+  def self.yaml_serializer
+    defined?(Gem::YAMLSerializer) ? Gem::YAMLSerializer : Bundler::YAMLSerializer
+  end
+
   ##
   # Searches and returns the directory for settings.
   #
@@ -151,6 +172,16 @@ module RDoc
     end
   end
 
+  ##
+  # Returns +File.mtime(file)+, or +nil+ if the file cannot be stat'd
+  # (missing, permission denied, etc.).
+
+  def self.safe_mtime(file)
+    File.mtime(file)
+  rescue SystemCallError
+    nil
+  end
+
   autoload :RDoc,           "#{__dir__}/rdoc/rdoc"
 
   autoload :CrossReference, "#{__dir__}/rdoc/cross_reference"
@@ -160,7 +191,7 @@ module RDoc
   autoload :Generator,      "#{__dir__}/rdoc/generator"
   autoload :Options,        "#{__dir__}/rdoc/options"
   autoload :Parser,         "#{__dir__}/rdoc/parser"
-  autoload :Servlet,        "#{__dir__}/rdoc/servlet"
+  autoload :Server,         "#{__dir__}/rdoc/server"
   autoload :RI,             "#{__dir__}/rdoc/ri"
   autoload :Stats,          "#{__dir__}/rdoc/stats"
   autoload :Store,          "#{__dir__}/rdoc/store"
@@ -189,7 +220,6 @@ module RDoc
   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"
@@ -198,8 +228,6 @@ module RDoc
   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"

data/lib/rubygems_plugin.rb

@@ -10,14 +10,5 @@
 
 require_relative 'rdoc/rubygems_hook'
 
-# To install dependency libraries of RDoc, you need to run bundle install.
-# At that time, rdoc/markdown is not generated.
-# If generate and remove are executed at that time, an error will occur.
-# So, we can't register generate and remove to Gem at that time.
-begin
-  require_relative 'rdoc/markdown'
-rescue LoadError
-else
-  Gem.done_installing(&RDoc::RubyGemsHook.method(:generate))
-  Gem.pre_uninstall(&RDoc::RubyGemsHook.method(:remove))
-end
+Gem.done_installing(&RDoc::RubyGemsHook.method(:generate))
+Gem.pre_uninstall(&RDoc::RubyGemsHook.method(:remove))

data/rdoc-logo.svg

@@ -0,0 +1,43 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="168" height="198" viewBox="298 140 712 840" role="img" aria-labelledby="title desc">
+  <title id="title">RDoc</title>
+  <desc id="desc">A red document outline with a folded corner and a Ruby gem.</desc>
+  <style>
+    .surface {
+      fill: transparent;
+    }
+
+    .stroke {
+      stroke: url(#rdoc-red);
+    }
+
+    .solid {
+      fill: url(#rdoc-red);
+    }
+  </style>
+  <defs>
+    <linearGradient id="rdoc-red" x1="338" y1="178" x2="973" y2="938" gradientUnits="userSpaceOnUse">
+      <stop id="rdoc-red-start" offset="0" stop-color="#e62923"/>
+      <stop id="rdoc-red-mid" offset="0.56" stop-color="#e62923"/>
+      <stop id="rdoc-red-end" offset="1" stop-color="#e62923"/>
+    </linearGradient>
+    <filter id="soft-red-shadow" x="-10%" y="-10%" width="120%" height="120%">
+      <feDropShadow dx="0" dy="5" stdDeviation="5" flood-color="#e62923" flood-opacity="0.1"/>
+    </filter>
+  </defs>
+
+  <g filter="url(#soft-red-shadow)" fill="none" class="stroke" stroke-linecap="round" stroke-linejoin="round">
+    <path class="surface" d="M382 178h326l149 149v499c0 24-20 44-44 44H382c-24 0-44-20-44-44V222c0-24 20-44 44-44Z" stroke="none"/>
+    <path d="M685 870H382c-24 0-44-20-44-44V222c0-24 20-44 44-44h326l149 149v246" stroke-width="26"/>
+    <path class="solid" d="M708 178v126c0 24 19 43 43 43h106" stroke="none"/>
+    <path d="M708 178 857 327" stroke-width="26"/>
+
+    <path d="M440 411h216" stroke-width="26"/>
+    <path d="M440 506h216" stroke-width="26"/>
+    <path d="M440 605h145" stroke-width="26"/>
+
+    <path class="surface" d="M668 609h224l81 97-195 232-191-232 81-97Z" stroke-width="26"/>
+    <path d="M668 609 700 706 778 609 858 706 892 609" stroke-width="20"/>
+    <path d="M587 706h386" stroke-width="20"/>
+    <path d="M700 706 778 938 858 706" stroke-width="20"/>
+  </g>
+</svg>

data/rdoc.gemspec

@@ -26,7 +26,7 @@ RDoc produces HTML and command-line documentation for Ruby projects.
 RDoc includes the +rdoc+ and +ri+ tools for generating and displaying documentation from the command-line.
   DESCRIPTION
   s.homepage = "https://ruby.github.io/rdoc"
-  s.licenses = ["Ruby"]
+  s.licenses = ["Ruby", "GPL-2.0-only"]
 
   s.metadata["homepage_uri"] = s.homepage
   s.metadata["source_code_uri"] = "https://github.com/ruby/rdoc"
@@ -38,10 +38,10 @@ RDoc includes the +rdoc+ and +ri+ tools for generating and displaying documentat
   # for ruby core repository. It was generated by
   # `git ls-files -z`.split("\x0").each {|f| puts "    #{f.dump}," unless f.start_with?(*%W[test/ spec/ features/ .]) }
   non_lib_files = [
-    "CONTRIBUTING.rdoc",
+    "CONTRIBUTING.md",
     "CVE-2013-0256.rdoc",
-    "ExampleMarkdown.md",
-    "ExampleRDoc.rdoc",
+    "doc/markup_reference/markdown.md",
+    "doc/markup_reference/rdoc.rdoc",
     "History.rdoc",
     "LEGAL.rdoc",
     "LICENSE.rdoc",
@@ -51,6 +51,7 @@ RDoc includes the +rdoc+ and +ri+ tools for generating and displaying documentat
     "exe/rdoc",
     "exe/ri",
     "man/ri.1",
+    "rdoc-logo.svg",
     "rdoc.gemspec",
   ]
   base = __dir__
@@ -60,13 +61,14 @@ RDoc includes the +rdoc+ and +ri+ tools for generating and displaying documentat
 
   s.files = (non_lib_files + template_files + lib_files).uniq
 
-  s.rdoc_options = ["--main", "README.md"]
+  s.rdoc_options = ["--main", "README.md", "--copy-files", "rdoc-logo.svg"]
   s.extra_rdoc_files += s.files.grep(%r[\A[^\/]+\.(?:rdoc|md)\z])
 
-  s.required_ruby_version = Gem::Requirement.new(">= 2.6.0")
+  s.required_ruby_version = Gem::Requirement.new(">= 3.2.0")
   s.required_rubygems_version = Gem::Requirement.new(">= 2.2")
 
-  s.add_dependency 'psych', '>= 4.0.0'
   s.add_dependency 'erb'
   s.add_dependency 'tsort'
+  s.add_dependency 'prism', '>= 1.6.0'
+  s.add_dependency 'rbs', '>= 4.0.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rdoc
 version: !ruby/object:Gem::Version
-  version: 6.17.0
+  version: 8.1.0
 platform: ruby
 authors:
 - Eric Hodel
@@ -13,24 +13,24 @@ authors:
 - ITOYANAGI Sakura
 bindir: exe
 cert_chain: []
-date: 2025-12-07 00:00:00.000000000 Z
+date: 2026-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: psych
+  name: erb
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.0.0
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.0.0
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: erb
+  name: tsort
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -44,19 +44,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: tsort
+  name: prism
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.6.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.6.0
+- !ruby/object:Gem::Dependency
+  name: rbs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
 description: |
   RDoc produces HTML and command-line documentation for Ruby projects.
   RDoc includes the +rdoc+ and +ri+ tools for generating and displaying documentation from the command-line.
@@ -73,10 +87,8 @@ executables:
 - ri
 extensions: []
 extra_rdoc_files:
-- CONTRIBUTING.rdoc
+- CONTRIBUTING.md
 - CVE-2013-0256.rdoc
-- ExampleMarkdown.md
-- ExampleRDoc.rdoc
 - History.rdoc
 - LEGAL.rdoc
 - LICENSE.rdoc
@@ -84,22 +96,21 @@ extra_rdoc_files:
 - RI.md
 - TODO.rdoc
 files:
-- CONTRIBUTING.rdoc
+- CONTRIBUTING.md
 - CVE-2013-0256.rdoc
-- ExampleMarkdown.md
-- ExampleRDoc.rdoc
 - History.rdoc
 - LEGAL.rdoc
 - LICENSE.rdoc
 - README.md
 - RI.md
 - TODO.rdoc
+- doc/markup_reference/markdown.md
+- doc/markup_reference/rdoc.rdoc
 - exe/rdoc
 - exe/ri
 - lib/rdoc.rb
 - lib/rdoc/code_object.rb
 - lib/rdoc/code_object/alias.rb
-- lib/rdoc/code_object/anon_class.rb
 - lib/rdoc/code_object/any_method.rb
 - lib/rdoc/code_object/attr.rb
 - lib/rdoc/code_object/class_module.rb
@@ -107,9 +118,7 @@ files:
 - lib/rdoc/code_object/context.rb
 - lib/rdoc/code_object/context/section.rb
 - lib/rdoc/code_object/extend.rb
-- lib/rdoc/code_object/ghost_method.rb
 - lib/rdoc/code_object/include.rb
-- lib/rdoc/code_object/meta_method.rb
 - lib/rdoc/code_object/method_attr.rb
 - lib/rdoc/code_object/mixin.rb
 - lib/rdoc/code_object/normal_class.rb
@@ -133,6 +142,7 @@ files:
 - lib/rdoc/generator/pot/po.rb
 - lib/rdoc/generator/pot/po_entry.rb
 - lib/rdoc/generator/ri.rb
+- lib/rdoc/generator/template/aliki/DESIGN.md
 - lib/rdoc/generator/template/aliki/_aside_toc.rhtml
 - lib/rdoc/generator/template/aliki/_footer.rhtml
 - lib/rdoc/generator/template/aliki/_head.rhtml
@@ -152,8 +162,11 @@ files:
 - lib/rdoc/generator/template/aliki/css/rdoc.css
 - lib/rdoc/generator/template/aliki/index.rhtml
 - lib/rdoc/generator/template/aliki/js/aliki.js
+- lib/rdoc/generator/template/aliki/js/bash_highlighter.js
 - lib/rdoc/generator/template/aliki/js/c_highlighter.js
-- lib/rdoc/generator/template/aliki/js/search.js
+- lib/rdoc/generator/template/aliki/js/search_controller.js
+- lib/rdoc/generator/template/aliki/js/search_navigation.js
+- lib/rdoc/generator/template/aliki/js/search_ranker.js
 - lib/rdoc/generator/template/aliki/js/theme-toggle.js
 - lib/rdoc/generator/template/aliki/page.rhtml
 - lib/rdoc/generator/template/aliki/servlet_not_found.rhtml
@@ -221,29 +234,25 @@ files:
 - lib/rdoc/known_classes.rb
 - lib/rdoc/markdown.kpeg
 - lib/rdoc/markdown.rb
+- lib/rdoc/markdown/byte_runtime.rb
 - lib/rdoc/markdown/entities.rb
-- lib/rdoc/markdown/literals.kpeg
-- lib/rdoc/markdown/literals.rb
 - lib/rdoc/markup.rb
-- lib/rdoc/markup/attr_changer.rb
-- lib/rdoc/markup/attr_span.rb
-- lib/rdoc/markup/attribute_manager.rb
-- lib/rdoc/markup/attributes.rb
 - lib/rdoc/markup/blank_line.rb
 - lib/rdoc/markup/block_quote.rb
 - lib/rdoc/markup/document.rb
+- lib/rdoc/markup/element.rb
 - lib/rdoc/markup/formatter.rb
 - lib/rdoc/markup/hard_break.rb
 - lib/rdoc/markup/heading.rb
 - lib/rdoc/markup/include.rb
 - lib/rdoc/markup/indented_paragraph.rb
+- lib/rdoc/markup/inline_parser.rb
 - lib/rdoc/markup/list.rb
 - lib/rdoc/markup/list_item.rb
 - lib/rdoc/markup/paragraph.rb
 - lib/rdoc/markup/parser.rb
 - lib/rdoc/markup/pre_process.rb
 - lib/rdoc/markup/raw.rb
-- lib/rdoc/markup/regexp_handling.rb
 - lib/rdoc/markup/rule.rb
 - lib/rdoc/markup/table.rb
 - lib/rdoc/markup/to_ansi.rb
@@ -264,13 +273,13 @@ files:
 - lib/rdoc/parser/c.rb
 - lib/rdoc/parser/changelog.rb
 - lib/rdoc/parser/markdown.rb
-- lib/rdoc/parser/prism_ruby.rb
+- lib/rdoc/parser/rbs.rb
 - lib/rdoc/parser/rd.rb
-- lib/rdoc/parser/ripper_state_lex.rb
 - lib/rdoc/parser/ruby.rb
-- lib/rdoc/parser/ruby_tools.rb
+- lib/rdoc/parser/ruby_colorizer.rb
 - lib/rdoc/parser/simple.rb
 - lib/rdoc/parser/text.rb
+- lib/rdoc/rbs_helper.rb
 - lib/rdoc/rd.rb
 - lib/rdoc/rd/block_parser.rb
 - lib/rdoc/rd/block_parser.ry
@@ -282,10 +291,11 @@ files:
 - lib/rdoc/ri/driver.rb
 - lib/rdoc/ri/formatter.rb
 - lib/rdoc/ri/paths.rb
+- lib/rdoc/ri/servlet.rb
 - lib/rdoc/ri/store.rb
 - lib/rdoc/ri/task.rb
 - lib/rdoc/rubygems_hook.rb
-- lib/rdoc/servlet.rb
+- lib/rdoc/server.rb
 - lib/rdoc/stats.rb
 - lib/rdoc/stats/normal.rb
 - lib/rdoc/stats/quiet.rb
@@ -298,10 +308,12 @@ files:
 - lib/rdoc/version.rb
 - lib/rubygems_plugin.rb
 - man/ri.1
+- rdoc-logo.svg
 - rdoc.gemspec
 homepage: https://ruby.github.io/rdoc
 licenses:
 - Ruby
+- GPL-2.0-only
 metadata:
   homepage_uri: https://ruby.github.io/rdoc
   source_code_uri: https://github.com/ruby/rdoc
@@ -309,20 +321,22 @@ metadata:
 rdoc_options:
 - "--main"
 - README.md
+- "--copy-files"
+- rdoc-logo.svg
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '2.2'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.20
 specification_version: 4
 summary: RDoc produces HTML and command-line documentation for Ruby projects
 test_files: []

data/CONTRIBUTING.rdoc

@@ -1,219 +0,0 @@
-= Developer Introduction
-
-So you want to write a generator, fix a bug, or otherwise work with RDoc.  This
-document provides an overview of how RDoc works from parsing options to
-generating output.  Most of the documentation can be found in the specific
-classes for each feature.
-
-== Bugs
-
-If you think you found a bug, file a ticket on the {issues
-tracker}[https://github.com/ruby/rdoc/issues] on github.
-
-If your bug involves an error RDoc produced please include a sample file that
-illustrates the problem or link to the repository or gem that is associated
-with the bug.
-
-Please include steps to reproduce the issue.  Here are some examples of good
-issues:
-
-* https://github.com/ruby/rdoc/issues/55
-* https://github.com/ruby/rdoc/issues/61
-
-== Developer Quick Start
-
-RDoc uses bundler for development.  To get ready to work on RDoc run:
-
-  $ gem install bundler
-  [...]
-  $ bundle install
-  [...]
-  $ rake
-  [...]
-
-This will install all the necessary dependencies for development with rake,
-generate documentation and run the tests for the first time.
-
-If the tests don't pass on the first run check the {GitHub Actions page}[https://github.com/ruby/rdoc/actions] to see if there are any known failures
-(there shouldn't be).
-
-You can now use `rake` and `autotest` to run the tests.
-
-Note: the `rake` command must be used first before running any tests, because
-it's used to generate various parsers implemented in RDoc. Also `rake clean` is
-helpful to delete these generated files.
-
-== Glossary
-
-Here are definitions for some common terms in the RDoc documentation.  The
-list also briefly describes how the components of RDoc interact.
-
-parser::
-  Parses files and creates a documentation tree from the contents.
-
-documentation tree::
-  The documentation tree represents files, classes, modules, methods,
-  constants, includes, comments and other ruby syntax features as a tree.
-  RDoc walks this tree with a generator to create documentation.
-
-generator::
-  Walks the documentation tree and generates output.
-
-  RDoc ships with two generators, the Darkfish generator creates HTML and the
-  RI generator creates an RI data store.
-
-markup parser::
-  Parses comments from a file into a generic markup tree.
-
-  The markup parsers allow RDoc to handle RDoc, TomDoc, rd and Markdown format
-  documentation with common formatters.
-
-markup tree::
-  Each parsed comment has a markup tree that represents common markup items
-  such as headings, paragraphs, lists or verbatim text sections for example
-  code or output.
-
-  A generator uses a formatters to walks the tree to create output.  Some
-  generators use multiple formatters on a markup tree to produce the output.
-
-formatter::
-  Converts a parsed markup tree into some form other form of markup.
-
-  Formatters can either produce a one-to-one conversion, such as ToHtml, or
-  extract part of the parsed result, such as ToHtmlSnippet which outputs the
-  first 100 characters as HTML.
-
-== Plugins
-
-When 'rdoc/rdoc' is loaded RDoc looks for 'rdoc/discover' files in your
-installed gems.  This can be used to load parsers, alternate generators, or
-additional preprocessor directives.  An rdoc plugin layout should look
-something like this:
-
-  lib/rdoc/discover.rb
-  lib/my/rdoc/plugin.rb
-  # etc.
-
-In your rdoc/discover.rb file you will want to wrap the loading of your plugin
-in an RDoc version check like this:
-
-  begin
-    gem 'rdoc', '~> 3'
-    require 'my/rdoc/plugin'
-  rescue Gem::LoadError
-  end
-
-=== Plugin Types
-
-In RDoc you can change the following behaviors:
-
-* Add a parser for a new file format
-* Add a new output generator
-* Add a new markup directive
-* Add a new type of documentation markup
-* Add a new type of formatter
-
-All of these are described below
-
-== Option Parsing
-
-Option parsing is handled by RDoc::Options.  When you're writing a generator
-you can provide the user with extra options by providing a class method
-+setup_options+.  The option parser will call this after your generator is
-loaded.  See RDoc::Generator for details.
-
-== File Parsing
-
-After options are parsed, RDoc parses files from the files and directories in
-ARGV.  RDoc compares the filename against what each parser claims it can parse
-via RDoc::Parser#parse_files_matching.  For example, RDoc::Parser::C can parse
-C files, C headers, C++ files, C++ headers and yacc grammars.
-
-Once a matching parser class is found it is instantiated and +scan+ is called.
-The parser needs to extract documentation from the file and add it to the RDoc
-document tree.  Usually this involves starting at the root and adding a class
-or a module (RDoc::TopLevel#add_class and RDoc::TopLevel#add_module) and
-proceeding to add classes, modules and methods to each nested item.
-
-When the parsers are finished the document tree is cleaned up to remove
-dangling references to aliases and includes that were not found (and may exist
-in a separate library) through RDoc::ClassModule#complete.
-
-To write your own parser for a new file format see RDoc::Parser.
-
-=== Documentation Tree
-
-The parsers build a documentation tree that is composed of RDoc::CodeObject and
-its subclasses.  There are various methods to walk the tree to extract
-information, see RDoc::Context and its subclasses.
-
-Within a class or module, attributes, methods and constants are divided into
-sections.  The section represents a functional grouping of parts of the class.
-TomDoc uses the sections "Public", "Internal" and "Deprecated".  The sections
-can be enumerated using RDoc::Context#each_section.
-
-== Output Generation
-
-An RDoc generator turns the documentation tree into some other kind of output.
-RDoc comes with an HTML generator (RDoc::Generator::Darkfish) and an RI
-database generator (RDoc::Generator::RI).  The output a generator creates does
-not have to be human-readable.
-
-To create your own generator see RDoc::Generator.
-
-=== Comments
-
-In RDoc 3.10 and newer the comment on an RDoc::CodeObject is now an
-RDoc::Comment object instead of a String.  This is to support various
-documentation markup formats like rdoc, TomDoc and rd.  The comments are
-normalized to remove comment markers and remove indentation then parsed lazily
-via RDoc::Comment#document to create a generic markup tree that can be
-processed by a formatter.
-
-To add your own markup format see RDoc::Markup@Other+directives
-
-==== Formatters
-
-To transform a comment into some form of output an RDoc::Markup::Formatter
-subclass is used like RDoc::Markup::ToHtml.  A formatter is a visitor that
-walks a parsed comment tree (an RDoc::Markup::Document) of any format.  To help
-write a formatter RDoc::Markup::FormatterTestCase exists for generic parsers,
-and RDoc::Markup::TextFormatterTestCase which contains extra test cases for
-text-type output (like +ri+ output).
-
-RDoc ships with formatters that will turn a comment into HTML, rdoc-markup-like
-text, ANSI or terminal backspace highlighted text, HTML, cross-referenced HTML,
-an HTML snippet free of most markup, an HTML label for use in id attributes, a
-table-of-contents page, and text with only code blocks.
-
-The output of the formatter does not need to be text or text-like.
-RDoc::Markup::ToLabel creates an HTML-safe label for use in an HTML id
-attribute.  A formatter could count the number of words and the average word
-length for a comment, for example.
-
-==== Directives
-
-For comments in markup you can add new directives (:nodoc: is a directive).
-Directives may replace text or store it off for later use.
-
-See RDoc::Markup::PreProcess::register for details.
-
-=== JSONIndex
-
-RDoc contains a special generator, RDoc::Generator::JSONIndex, which creates a
-JSON-based search index and includes a search engine for use with HTML output.
-This generator can be used to add searching to any HTML output and is designed
-to be called from inside an HTML generator.
-
-== Markup
-
-Additional documentation markup formats can be added to RDoc.  A markup
-parsing class must respond to \::parse and accept a String argument containing
-the markup format.  An RDoc::Document containing documentation items
-(RDoc::Markup::Heading, RDoc::Markup::Paragraph, RDoc::Markup::Verbatim, etc.)
-must be returned.
-
-To register the parser with rdoc, add the markup type's name and class to the
-RDoc::Text::MARKUP_FORMAT hash like:
-
-  RDoc::Text::MARKUP_FORMAT['rdoc'] = RDoc::Markup