rdoc 7.2.0 → 8.1.0

data/lib/rdoc/tom_doc.rb

@@ -1,257 +1,259 @@
 # frozen_string_literal: true
 # :markup: tomdoc
 
-# A parser for TomDoc based on TomDoc 1.0.0-rc1 (02adef9b5a)
-#
-# The TomDoc specification can be found at http://tomdoc.org.
-#
-# To choose TomDoc as your only default format see RDoc::Options@Saved+Options
-# for instructions on setting up a <code>.rdoc_options</code> file to store
-# your project default.
-#
-# There are a few differences between this parser and the specification.  A
-# best-effort was made to follow the specification as closely as possible but
-# some choices to deviate were made.
-#
-# A future version of RDoc will warn when a MUST or MUST NOT is violated and
-# may warn when a SHOULD or SHOULD NOT is violated.  RDoc will always try
-# to emit documentation even if given invalid TomDoc.
-#
-# Here are some implementation choices this parser currently makes:
-#
-# This parser allows rdoc-style inline markup but you should not depended on
-# it.
-#
-# This parser allows a space between the comment and the method body.
-#
-# This parser does not require the default value to be described for an
-# optional argument.
-#
-# This parser does not examine the order of sections.  An Examples section may
-# precede the Arguments section.
-#
-# This class is documented in TomDoc format.  Since this is a subclass of the
-# RDoc markup parser there isn't much to see here, unfortunately.
-
-class RDoc::TomDoc < RDoc::Markup::Parser
-
-  # Internal: Token accessor
-
-  attr_reader :tokens
-
-  # Internal: Adds a post-processor which sets the RDoc section based on the
-  # comment's status.
+module RDoc
+  # A parser for TomDoc based on TomDoc 1.0.0-rc1 (02adef9b5a)
   #
-  # Returns nothing.
-
-  def self.add_post_processor # :nodoc:
-    RDoc::Markup::PreProcess.post_process do |comment, code_object|
-      next unless code_object and
-                  RDoc::Comment === comment and comment.format == 'tomdoc'
-
-      comment.text.gsub!(/\A(\s*# |)(Public|Internal|Deprecated):\s+/) do
-        section = code_object.add_section $2
-        code_object.temporary_section = section
-
-        $1
-      end
-    end
-  end
-
-  add_post_processor
-
-  # Public: Parses TomDoc from text
+  # The TomDoc specification can be found at http://tomdoc.org.
   #
-  # text - A String containing TomDoc-format text.
+  # To choose TomDoc as your only default format see RDoc::Options@Saved+Options
+  # for instructions on setting up a <code>.rdoc_options</code> file to store
+  # your project default.
   #
-  # Examples
+  # There are a few differences between this parser and the specification.  A
+  # best-effort was made to follow the specification as closely as possible but
+  # some choices to deviate were made.
   #
-  #   RDoc::TomDoc.parse <<-TOMDOC
-  #   This method does some things
+  # A future version of RDoc will warn when a MUST or MUST NOT is violated and
+  # may warn when a SHOULD or SHOULD NOT is violated.  RDoc will always try
+  # to emit documentation even if given invalid TomDoc.
   #
-  #   Returns nothing.
-  #   TOMDOC
-  #   # => #<RDoc::Markup::Document:0xXXX @parts=[...], @file=nil>
+  # Here are some implementation choices this parser currently makes:
   #
-  # Returns an RDoc::Markup::Document representing the TomDoc format.
-
-  def self.parse(text)
-    parser = new
-
-    parser.tokenize text
-    doc = RDoc::Markup::Document.new
-    parser.parse doc
-    doc
-  end
-
-  # Internal: Extracts the Signature section's method signature
+  # This parser allows rdoc-style inline markup but you should not depended on
+  # it.
   #
-  # comment - An RDoc::Comment that will be parsed and have the signature
-  #           extracted
+  # This parser allows a space between the comment and the method body.
   #
-  # Returns a String containing the signature and nil if not
-
-  def self.signature(comment)
-    return unless comment.tomdoc?
+  # This parser does not require the default value to be described for an
+  # optional argument.
+  #
+  # This parser does not examine the order of sections.  An Examples section may
+  # precede the Arguments section.
+  #
+  # This class is documented in TomDoc format.  Since this is a subclass of the
+  # RDoc markup parser there isn't much to see here, unfortunately.
 
-    document = comment.parse
+  class TomDoc < Markup::Parser
 
-    signature = nil
-    found_heading = false
-    found_signature = false
+    # Internal: Token accessor
 
-    document.parts.delete_if do |part|
-      next false if found_signature
+    attr_reader :tokens
 
-      found_heading ||=
-        RDoc::Markup::Heading === part && part.text == 'Signature'
+    # Internal: Adds a post-processor which sets the RDoc section based on the
+    # comment's status.
+    #
+    # Returns nothing.
 
-      next false unless found_heading
+    def self.add_post_processor # :nodoc:
+      Markup::PreProcess.post_process do |comment, code_object|
+        next unless code_object and
+                    Comment === comment and comment.format == 'tomdoc'
 
-      next true if RDoc::Markup::BlankLine === part
+        comment.text.gsub!(/\A(\s*# |)(Public|Internal|Deprecated):\s+/) do
+          section = code_object.add_section $2
+          code_object.temporary_section = section
 
-      if RDoc::Markup::Verbatim === part then
-        signature = part
-        found_signature = true
+          $1
+        end
       end
     end
 
-    signature and signature.text
-  end
+    add_post_processor
+
+    # Public: Parses TomDoc from text
+    #
+    # text - A String containing TomDoc-format text.
+    #
+    # Examples
+    #
+    #   RDoc::TomDoc.parse <<-TOMDOC
+    #   This method does some things
+    #
+    #   Returns nothing.
+    #   TOMDOC
+    #   # => #<RDoc::Markup::Document:0xXXX @parts=[...], @file=nil>
+    #
+    # Returns an RDoc::Markup::Document representing the TomDoc format.
+
+    def self.parse(text)
+      parser = new
+
+      parser.tokenize text
+      doc = Markup::Document.new
+      parser.parse doc
+      doc
+    end
 
-  # Public: Creates a new TomDoc parser.  See also RDoc::Markup::parse
+    # Internal: Extracts the Signature section's method signature
+    #
+    # comment - An RDoc::Comment that will be parsed and have the signature
+    #           extracted
+    #
+    # Returns a String containing the signature and nil if not
 
-  def initialize
-    super
+    def self.signature(comment)
+      return unless comment.tomdoc?
 
-    @section      = nil
-    @seen_returns = false
-  end
+      document = comment.parse
 
-  # Internal: Builds a heading from the token stream
-  #
-  # level - The level of heading to create
-  #
-  # Returns an RDoc::Markup::Heading
+      signature = nil
+      found_heading = false
+      found_signature = false
 
-  def build_heading(level)
-    heading = super
+      document.parts.delete_if do |part|
+        next false if found_signature
 
-    @section = heading.text
+        found_heading ||=
+          Markup::Heading === part && part.text == 'Signature'
 
-    heading
-  end
+        next false unless found_heading
 
-  # Internal: Builds a verbatim from the token stream.  A verbatim in the
-  # Examples section will be marked as in Ruby format.
-  #
-  # margin - The indentation from the margin for lines that belong to this
-  #          verbatim section.
-  #
-  # Returns an RDoc::Markup::Verbatim
+        next true if Markup::BlankLine === part
+
+        if Markup::Verbatim === part
+          signature = part
+          found_signature = true
+        end
+      end
 
-  def build_verbatim(margin)
-    verbatim = super
+      signature and signature.text
+    end
 
-    verbatim.format = :ruby if @section == 'Examples'
+    # Public: Creates a new TomDoc parser.  See also RDoc::Markup::parse
 
-    verbatim
-  end
+    def initialize
+      super
 
-  # Internal: Builds a paragraph from the token stream
-  #
-  # margin - Unused
-  #
-  # Returns an RDoc::Markup::Paragraph.
+      @section      = nil
+      @seen_returns = false
+    end
 
-  def build_paragraph(margin)
-    p :paragraph_start => margin if @debug
+    # Internal: Builds a heading from the token stream
+    #
+    # level - The level of heading to create
+    #
+    # Returns an RDoc::Markup::Heading
 
-    paragraph = RDoc::Markup::Paragraph.new
+    def build_heading(level)
+      heading = super
 
-    until @tokens.empty? do
-      type, data, = get
+      @section = heading.text
 
-      case type
-      when :TEXT then
-        @section = 'Returns' if data =~ /\A(Returns|Raises)/
+      heading
+    end
 
-        paragraph << data
-      when :NEWLINE then
-        if :TEXT == peek_token[0] then
-          # Lines beginning with 'Raises' in the Returns section should not be
-          # treated as multiline text
-          if 'Returns' == @section and
-            peek_token[1].start_with?('Raises') then
-            break
+    # Internal: Builds a verbatim from the token stream.  A verbatim in the
+    # Examples section will be marked as in Ruby format.
+    #
+    # margin - The indentation from the margin for lines that belong to this
+    #          verbatim section.
+    #
+    # Returns an RDoc::Markup::Verbatim
+
+    def build_verbatim(margin)
+      verbatim = super
+
+      verbatim.format = :ruby if @section == 'Examples'
+
+      verbatim
+    end
+
+    # Internal: Builds a paragraph from the token stream
+    #
+    # margin - Unused
+    #
+    # Returns an RDoc::Markup::Paragraph.
+
+    def build_paragraph(margin)
+      p :paragraph_start => margin if @debug
+
+      paragraph = Markup::Paragraph.new
+
+      until @tokens.empty? do
+        type, data, = get
+
+        case type
+        when :TEXT
+          @section = 'Returns' if data =~ /\A(Returns|Raises)/
+
+          paragraph << data
+        when :NEWLINE
+          if :TEXT == peek_token[0]
+            # Lines beginning with 'Raises' in the Returns section should not be
+            # treated as multiline text
+            if 'Returns' == @section and
+              peek_token[1].start_with?('Raises')
+              break
+            else
+              paragraph << ' '
+            end
           else
-            paragraph << ' '
+            break
           end
         else
+          unget
           break
         end
-      else
-        unget
-        break
       end
-    end
 
-    p :paragraph_end => margin if @debug
+      p :paragraph_end => margin if @debug
 
-    paragraph
-  end
+      paragraph
+    end
+
+    ##
+    # Detects a section change to "Returns" and adds a heading
 
-  ##
-  # Detects a section change to "Returns" and adds a heading
+    def parse_text(parent, indent) # :nodoc:
+      paragraph = build_paragraph indent
 
-  def parse_text(parent, indent) # :nodoc:
-    paragraph = build_paragraph indent
+      if false == @seen_returns and 'Returns' == @section
+        @seen_returns = true
+        parent << Markup::Heading.new(3, 'Returns')
+        parent << Markup::BlankLine.new
+      end
 
-    if false == @seen_returns and 'Returns' == @section then
-      @seen_returns = true
-      parent << RDoc::Markup::Heading.new(3, 'Returns')
-      parent << RDoc::Markup::BlankLine.new
+      parent << paragraph
     end
 
-    parent << paragraph
-  end
+    # Internal: Turns text into an Array of tokens
+    #
+    # text - A String containing TomDoc-format text.
+    #
+    # Returns self.
+
+    def tokenize(text)
+      text = text.sub(/\A(Public|Internal|Deprecated):\s+/, '')
+
+      setup_scanner text
+
+      until @s.eos? do
+        pos = @s.pos
+
+        # leading spaces will be reflected by the column of the next token
+        # the only thing we loose are trailing spaces at the end of the file
+        next if @s.scan(/ +/)
+
+        @tokens << case
+                   when @s.scan(/\r?\n/)
+                     token = [:NEWLINE, @s.matched, *pos]
+                     @s.newline!
+                     token
+                   when @s.scan(/(Examples|Signature)$/)
+                     @tokens << [:HEADER, 3, *pos]
+
+                     [:TEXT, @s[1], *pos]
+                   when @s.scan(/([:\w][\w\[\]]*)[ ]+- /)
+                     [:NOTE, @s[1], *pos]
+                   else
+                     @s.scan(/.*/)
+                     [:TEXT, @s.matched.sub(/\r$/, ''), *pos]
+                   end
+      end
 
-  # Internal: Turns text into an Array of tokens
-  #
-  # text - A String containing TomDoc-format text.
-  #
-  # Returns self.
-
-  def tokenize(text)
-    text = text.sub(/\A(Public|Internal|Deprecated):\s+/, '')
-
-    setup_scanner text
-
-    until @s.eos? do
-      pos = @s.pos
-
-      # leading spaces will be reflected by the column of the next token
-      # the only thing we loose are trailing spaces at the end of the file
-      next if @s.scan(/ +/)
-
-      @tokens << case
-                 when @s.scan(/\r?\n/) then
-                   token = [:NEWLINE, @s.matched, *pos]
-                   @s.newline!
-                   token
-                 when @s.scan(/(Examples|Signature)$/) then
-                   @tokens << [:HEADER, 3, *pos]
-
-                   [:TEXT, @s[1], *pos]
-                 when @s.scan(/([:\w][\w\[\]]*)[ ]+- /) then
-                   [:NOTE, @s[1], *pos]
-                 else
-                   @s.scan(/.*/)
-                   [:TEXT, @s.matched.sub(/\r$/, ''), *pos]
-                 end
+      self
     end
 
-    self
   end
-
 end

data/lib/rdoc/version.rb

@@ -5,6 +5,6 @@ module RDoc
   ##
   # RDoc version you are using
 
-  VERSION = '7.2.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"
@@ -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