rdoc 7.2.0 → 8.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1acd5d230eb6cc33e92e6ead29ef4edfd11d238750073c151197675b9d2ecef7
-  data.tar.gz: 765310288cb7611ae3990d238a894e9bd1e2d3431c2389c412f0a9407699a4ad
+  metadata.gz: a89bb304f22c095d76899a316b1ec9eefdb803303046da663dcd6c3bd52c370d
+  data.tar.gz: 2d76488b188447465d43934b24ff7ef3d1ec6c6f314512d86e8b7e0eb4185268
 SHA512:
-  metadata.gz: b3f79da244c49a5f13485ca9cec594aebd9cbcf9e2a8be2543aa186947ea645aac4ec783f4d3a19b9197ffa7b9e3df53e89dc774adf7ef4c394597c186039a76
-  data.tar.gz: c13a7678b03b25bbe56c854f7314fe50b8df2784d85d04b765294f5fd32baefb92a702e66233007689f1c4a65d7141c6e428af89e5953ce5e19976418e0fd76b
+  metadata.gz: d16d33de20366fadd59956e72dbffe115b0837ff10e37282bfec7b5420ebb5d177ddede87bafb2f735d9b5aca944558d6f60634004020c0d023dcef40852bc3d
+  data.tar.gz: d0105f405dd7f6c9debbe3ec1b47d0365a637a68bd291bda10b446cc5094929a6f40cec90a57981641f8d0741a42bf1447c03dda2b0772a44b3b9927b5b52717

data/CONTRIBUTING.md

@@ -146,7 +146,7 @@ bundle exec rake coverage
 RDoc ships with two HTML themes:
 
 - **Aliki** (default) - Modern theme with improved styling and navigation
-- **Darkfish** (deprecated) - Classic theme, will be removed in v8.0
+- **Darkfish** (deprecated) - Classic theme, will be removed in v9.0
 
 New feature development should focus on the Aliki theme. Darkfish will continue to receive bug fixes but no new features.
 
@@ -160,13 +160,12 @@ lib/rdoc/
 ├── version.rb                 # Version constant
 ├── task.rb                    # Rake task integration
 ├── parser/                    # Source code parsers
-│   ├── ruby.rb                # Ruby code parser
+│   ├── ruby.rb                # Prism-based Ruby parser
 │   ├── c.rb                   # C extension parser
-│   ├── prism_ruby.rb          # Prism-based Ruby parser
 │   └── ...
 ├── generator/                 # Documentation generators
 │   ├── aliki.rb               # HTML generator (default theme)
-│   ├── darkfish.rb            # HTML generator (deprecated, will be removed in v8.0)
+│   ├── darkfish.rb            # HTML generator (deprecated, will be removed in v9.0)
 │   ├── markup.rb              # Markup format generator
 │   ├── ri.rb                  # RI command generator
 │   └── template/              # ERB templates

data/LICENSE.rdoc

@@ -1,3 +1,7 @@
+:stopdoc:
+SPDX-License-Identifier: Ruby or GPL-2.0-only
+:startdoc:
+
 = License
 
 RDoc is copyrighted free software.

data/README.md

@@ -3,6 +3,10 @@
 - GitHub: [https://github.com/ruby/rdoc](https://github.com/ruby/rdoc)
 - Issues: [https://github.com/ruby/rdoc/issues](https://github.com/ruby/rdoc/issues)
 
+<p align="center" class="rdoc-logo">
+  <img src="rdoc-logo.svg" alt="RDoc" width="168" height="198">
+</p>
+
 ## 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.
@@ -37,7 +41,9 @@ rdoc --main README.md
 
 You'll find information on the various formatting tricks you can use in comment blocks in the documentation this generates.
 
-RDoc uses file extensions to determine how to process each file.  File names ending `.rb` and `.rbw` are assumed to be Ruby source.  Files ending `.c` are parsed as C files.  All other files are assumed to contain just Markup-style markup (with or without leading `#` comment markers).  If directory names are passed to RDoc, they are scanned recursively for C and Ruby source files only.
+RDoc uses file extensions to determine how to process each file.  File names ending `.rb` and `.rbw` are assumed to be Ruby source.  Files ending `.c` are parsed as C files.  Files ending `.rbs` are parsed as RBS signature files.  All other files are assumed to contain just Markup-style markup (with or without leading `#` comment markers).  If directory names are passed to RDoc, they are scanned recursively for C, Ruby, and RBS source files.
+
+RBS files can document classes, modules, methods, attributes, and constants.  When RBS declarations match objects already documented from Ruby source, their comments and type signatures extend the existing documentation.
 
 To generate documentation using `rake` see [RDoc::Task](https://ruby.github.io/rdoc/RDoc/Task.html).
 
@@ -159,7 +165,7 @@ To determine how well your project is documented run `rdoc -C lib` to get a docu
 RDoc ships with two built-in themes:
 
 - **Aliki** (default) - A modern, clean theme with improved navigation and search
-- **Darkfish** (deprecated) - The classic theme, will be removed in v8.0
+- **Darkfish** (deprecated) - The classic theme, will be removed in v9.0
 
 To use the Darkfish theme instead of the default Aliki theme:
 
@@ -180,6 +186,41 @@ There are also a few community-maintained themes for RDoc:
 
 Please follow the theme's README for usage instructions.
 
+## Live Preview Server
+
+RDoc includes a built-in server for previewing documentation while you edit source files. It parses your code once on startup, then watches for changes and auto-refreshes the browser.
+
+```shell
+rdoc --server
+```
+
+This starts a server at `http://localhost:4000`. You can specify a different port:
+
+```shell
+rdoc --server=8080
+```
+
+Or use the Rake task:
+
+```shell
+rake rdoc:server
+```
+
+### How It Works
+
+- Parses all source files on startup and serves pages from memory using the Aliki theme
+- A background thread polls file mtimes every second
+- When a file changes, only that file is re-parsed — the browser refreshes automatically
+- New files are detected and added; deleted files are removed
+
+**No external dependencies.** The server uses Ruby's built-in `TCPServer` (`socket` stdlib) — no WEBrick or other gems required.
+
+### Limitations
+
+- **Reopened classes and file deletion.** If a class is defined across multiple files (e.g. `Foo` in both `a.rb` and `b.rb`), deleting one file removes the entire class from the store, including parts from the other file. Saving the remaining file triggers a re-parse that restores it.
+- **Full cache invalidation.** Any file change clears all cached pages. This is simple and correct — rendering is fast (~ms per page), parsing is the expensive part and is done incrementally.
+- **No HTTPS or HTTP/2.** The server is intended for local development preview only.
+
 ## Bugs
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for information on filing a bug report.  It's OK to file a bug report for anything you're having a problem with.  If you can't figure out how to make RDoc produce the output you like that is probably a documentation bug.

data/doc/markup_reference/markdown.md

@@ -98,7 +98,9 @@ Use triple backticks with an optional language identifier:
     end
     ```
 
-Supported language for syntax highlighting: `ruby`, `rb` (alias to `ruby`), and `c`.
+Supported languages for syntax highlighting: `ruby` (and `rb` alias) with server-side
+highlighting, and `c`, `bash`/`sh`/`shell`/`console` with client-side JavaScript highlighting.
+Other info strings are accepted and added as a CSS class but receive no highlighting.
 
 ### Blockquotes
 
@@ -420,6 +422,9 @@ For example:
 * [Link to Blockquotes](#blockquotes)
 * [Link to Anchor Links](#anchor-links)
 
+When multiple headings produce the same anchor, RDoc appends `-1`, `-2`, etc.
+to subsequent duplicates, matching GitHub's behavior.
+
 ## Footnotes
 
 ### Reference Footnotes
@@ -535,7 +540,7 @@ See [rdoc.rdoc](rdoc.rdoc) for complete directive documentation.
 | Headings | `= Heading` | `# Heading` |
 | Bold | `*word*` | `**word**` |
 | Italic | `_word_` | `*word*` |
-| Monospace | `+word+` | `` `word` `` |
+| Monospace | `+word+` or `` `word` `` | `` `word` `` |
 | Links | `{text}[url]` | `[text](url)` |
 | Code blocks | Indent beyond margin | Indent 4 spaces or fence |
 | Block quotes | `>>>` | `>` |
@@ -551,8 +556,104 @@ See [rdoc.rdoc](rdoc.rdoc) for complete directive documentation.
 
 3. **Footnotes are collapsed** - Multiple paragraphs in a footnote become a single paragraph.
 
-4. **Syntax highlighting** - Only `ruby` and `c` are supported for fenced code blocks.
+4. **Syntax highlighting** - Only `ruby`/`rb` (server-side) and `c`, `bash`/`sh`/`shell`/`console` (client-side) receive syntax highlighting. Other info strings are accepted but not highlighted.
 
 5. **Fenced code blocks** - Only triple backticks are supported. Tilde fences (`~~~`) are not supported as they conflict with strikethrough syntax. Four or more backticks for nesting are also not supported.
 
 6. **Auto-linking** - RDoc automatically links class and method names in output, even without explicit link syntax.
+
+## Comparison with GitHub Flavored Markdown (GFM)
+
+This section compares RDoc's Markdown implementation with the
+[GitHub Flavored Markdown Spec](https://github.github.com/gfm/) (Version 0.29-gfm, 2019-04-06).
+
+### Block Elements
+
+| Feature | GFM | RDoc | Notes |
+|---------|:---:|:----:|-------|
+| ATX Headings (`#`) | ✅ | ✅ | Both support levels 1-6, optional closing `#` |
+| Setext Headings | ✅ | ✅ | `=` for H1, `-` for H2 |
+| Paragraphs | ✅ | ✅ | Full match |
+| Indented Code Blocks | ✅ | ✅ | 4 spaces or 1 tab |
+| Fenced Code (backticks) | ✅ 3+ | ⚠️ 3 only | RDoc doesn't support 4+ backticks for nesting |
+| Fenced Code (tildes) | ✅ `~~~` | ❌ | Conflicts with strikethrough syntax |
+| Info strings (language) | ✅ any | ⚠️ limited | `ruby`/`rb`, `c`, and `bash`/`sh`/`shell`/`console` highlighted; others accepted as CSS class |
+| Blockquotes | ✅ | ✅ | Full match, nested supported |
+| Lazy Continuation | ✅ | ⚠️ | Continuation text is included in blockquote but line break is lost (becomes a space) |
+| Bullet Lists | ✅ | ✅ | `*`, `+`, `-` supported |
+| Ordered Lists | ✅ `.` `)` | ⚠️ `.` only | RDoc doesn't support `)` delimiter; numbers are always renumbered from 1 |
+| Nested Lists | ✅ | ✅ | 4-space indentation |
+| Tables | ✅ | ✅ | Full alignment support |
+| Thematic Breaks | ✅ | ✅ | `---`, `***`, `___` |
+| HTML Blocks | ✅ 7 types | ⚠️ | See below |
+
+#### HTML Blocks
+
+GFM defines 7 types of HTML blocks:
+
+| Type | Description | GFM | RDoc | Notes |
+|------|-------------|:---:|:----:|-------|
+| 1 | `<script>`, `<pre>` | ✅ | ✅ | |
+| 1 | `<style>` | ✅ | ❌ | Available via `css` extension (disabled by default) |
+| 2 | HTML comments `<!-- -->` | ✅ | ✅ | |
+| 3 | Processing instructions `<? ?>` | ✅ | ❌ | |
+| 4 | Declarations `<!DOCTYPE>` | ✅ | ❌ | |
+| 5 | CDATA `<![CDATA[ ]]>` | ✅ | ❌ | |
+| 6 | Block-level tags | ✅ | ⚠️ | |
+| 7 | Any complete open/close tag | ✅ | ❌ | |
+
+RDoc uses a whitelist of block-level tags defined in
+[lib/rdoc/markdown.kpeg](https://github.com/ruby/rdoc/blob/master/lib/rdoc/markdown.kpeg)
+(see `HtmlBlockInTags`). HTML5 semantic elements like `<article>`, `<section>`,
+`<nav>`, `<header>`, `<footer>` are not supported.
+
+### Inline Elements
+
+| Feature | GFM | RDoc | Notes |
+|---------|:---:|:----:|-------|
+| Emphasis `*text*` `_text_` | ✅ | ⚠️ | Intraword emphasis not supported (see [Notes](#notes-and-limitations)) |
+| Strong `**text**` `__text__` | ✅ | ✅ | Full match |
+| Combined `***text***` | ✅ | ✅ | Full match |
+| Code spans | ✅ | ✅ | Multiple backticks supported |
+| Inline links | ✅ | ✅ | Full match |
+| Reference links | ✅ | ✅ | Full match |
+| Link titles | ✅ | ⚠️ | Parsed but not rendered |
+| Images | ✅ | ✅ | Full match |
+| Autolinks `<url>` | ✅ | ✅ | Full match |
+| Hard line breaks | ✅ | ⚠️ | 2+ trailing spaces only; backslash `\` at EOL not supported |
+| Backslash escapes | ✅ | ⚠️ | Subset of GFM's escapable characters (e.g., `~` not escapable) |
+| HTML entities | ✅ | ✅ | Named, decimal, hex |
+| Inline HTML | ✅ | ⚠️ | `<b>` converted to `<strong>`, `<i>` to `<em>`; `<strong>` itself is escaped |
+
+### GFM Extensions
+
+| Feature | GFM | RDoc | Notes |
+|---------|:---:|:----:|-------|
+| Strikethrough `~~text~~` | ✅ | ✅ | Full match |
+| Task Lists `[ ]` `[x]` | ✅ | ❌ | Not supported |
+| Extended Autolinks | ✅ | ⚠️ | See below |
+| Disallowed Raw HTML | ✅ | ❌ | No security filtering |
+
+#### GFM Extended Autolinks
+
+GFM automatically converts certain text patterns into links without requiring
+angle brackets (`<>`). RDoc also auto-links URLs and `www.` prefixes through
+its cross-reference system, but the behavior differs from GFM.
+
+GFM recognizes these patterns:
+
+- `www.example.com` — text starting with `www.` followed by a valid domain
+- `https://example.com` — URLs starting with `http://` or `https://`
+- `user@example.com` — valid email addresses
+
+RDoc auto-links `www.` prefixes and `http://`/`https://` URLs similarly to GFM.
+However, bare email addresses like `user@example.com` are not auto-linked;
+use `<user@example.com>` instead.
+
+### RDoc-Specific Features (not in GFM)
+
+- [Definition Lists](#definition-lists)
+- [Footnotes](#footnotes)
+- [Cross-references](#cross-references)
+- [Anchor Links](#anchor-links)
+- [Directives](#directives)

data/lib/rdoc/code_object/alias.rb

@@ -26,18 +26,12 @@ class RDoc::Alias < RDoc::CodeObject
   attr_reader :singleton
 
   ##
-  # Source file token stream
-
-  attr_reader :text
-
-  ##
-  # Creates a new Alias with a token stream of +text+ that aliases +old_name+
+  # Creates a new Alias that aliases +old_name+
   # to +new_name+, has +comment+ and is a +singleton+ context.
 
-  def initialize(text, old_name, new_name, comment, singleton: false)
+  def initialize(old_name, new_name, comment, singleton: false)
     super()
 
-    @text = text
     @singleton = singleton
     @old_name = old_name
     @new_name = new_name

data/lib/rdoc/code_object/any_method.rb

@@ -13,8 +13,10 @@ class RDoc::AnyMethod < RDoc::MethodAttr
   # 3::
   #   RDoc 4.1
   #   Added is_alias_for
+  # 4::
+  #   Added type_signature_lines (serialized as joined string)
 
-  MARSHAL_VERSION = 3 # :nodoc:
+  MARSHAL_VERSION = 4 # :nodoc:
 
   ##
   # Don't rename \#initialize to \::new
@@ -37,10 +39,10 @@ class RDoc::AnyMethod < RDoc::MethodAttr
   include RDoc::TokenStream
 
   ##
-  # Creates a new AnyMethod with a token stream +text+ and +name+
+  # Creates a new AnyMethod with name +name+
 
-  def initialize(text, name, singleton: false)
-    super(text, name, singleton: singleton)
+  def initialize(name, singleton: false)
+    super(name, singleton: singleton)
 
     @c_function = nil
     @dont_rename_initialize = false
@@ -53,13 +55,14 @@ class RDoc::AnyMethod < RDoc::MethodAttr
   # Adds +an_alias+ as an alias for this method in +context+.
 
   def add_alias(an_alias, context = nil)
-    method = self.class.new an_alias.text, an_alias.new_name, singleton: singleton
+    method = self.class.new an_alias.new_name, singleton: singleton
 
     method.record_location an_alias.file
     method.params = self.params
     method.visibility = self.visibility
     method.comment = an_alias.comment
     method.is_alias_for = self
+    method.type_signature_lines = self.type_signature_lines
     @aliases << method
     context.add_method method if context
     method
@@ -166,6 +169,7 @@ class RDoc::AnyMethod < RDoc::MethodAttr
       @parent.class,
       @section.title,
       is_alias_for,
+      @type_signature_lines&.join("\n"),
     ]
   end
 
@@ -204,9 +208,10 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     @parent_title  = array[13]
     @section_title = array[14]
     @is_alias_for  = array[15]
+    @type_signature_lines = array[16]&.split("\n")
 
     array[8].each do |new_name, document|
-      add_alias RDoc::Alias.new(nil, @name, new_name, RDoc::Comment.from_document(document), singleton: @singleton)
+      add_alias RDoc::Alias.new(@name, new_name, RDoc::Comment.from_document(document), singleton: @singleton)
     end
 
     @parent_name ||= if @full_name =~ /#/ then

data/lib/rdoc/code_object/attr.rb

@@ -10,8 +10,10 @@ class RDoc::Attr < RDoc::MethodAttr
   #   RDoc 4
   #    Added parent name and class
   #    Added section title
+  # 4::
+  #   Added type_signature_lines (serialized as joined string)
 
-  MARSHAL_VERSION = 3 # :nodoc:
+  MARSHAL_VERSION = 4 # :nodoc:
 
   ##
   # Is the attribute readable ('R'), writable ('W') or both ('RW')?
@@ -19,11 +21,11 @@ class RDoc::Attr < RDoc::MethodAttr
   attr_accessor :rw
 
   ##
-  # Creates a new Attr with body +text+, +name+, read/write status +rw+ and
+  # Creates a new Attr with +name+, read/write status +rw+ and
   # +comment+.  +singleton+ marks this as a class attribute.
 
-  def initialize(text, name, rw, comment, singleton: false)
-    super(text, name, singleton: singleton)
+  def initialize(name, rw, comment, singleton: false)
+    super(name, singleton: singleton)
 
     @rw = rw
     self.comment = comment
@@ -44,10 +46,11 @@ class RDoc::Attr < RDoc::MethodAttr
 
   def add_alias(an_alias, context)
     access_type = an_alias.new_name.end_with?('=') ? 'W' : 'R'
-    new_attr = self.class.new(text, an_alias.new_name, access_type, comment, singleton: singleton)
+    new_attr = self.class.new(an_alias.new_name, access_type, comment, singleton: singleton)
     new_attr.record_location an_alias.file
     new_attr.visibility = self.visibility
     new_attr.is_alias_for = self
+    new_attr.type_signature_lines = self.type_signature_lines
     @aliases << new_attr
     context.add_attribute new_attr
     new_attr
@@ -108,7 +111,8 @@ class RDoc::Attr < RDoc::MethodAttr
       @file.relative_name,
       @parent.full_name,
       @parent.class,
-      @section.title
+      @section.title,
+      @type_signature_lines&.join("\n"),
     ]
   end
 
@@ -140,6 +144,7 @@ class RDoc::Attr < RDoc::MethodAttr
     @parent_name   = array[8]
     @parent_class  = array[9]
     @section_title = array[10]
+    @type_signature_lines = array[11]&.split("\n")
 
     @file = RDoc::TopLevel.new array[7] if version > 1
 

data/lib/rdoc/code_object/class_module.rb

@@ -30,22 +30,20 @@ class RDoc::ClassModule < RDoc::Context
   attr_accessor :constant_aliases
 
   ##
-  # An array of `[comment, location]` pairs documenting this class/module.
+  # A hash of <tt>{ location => [comments] }</tt> documenting this class/module.
   # Use #add_comment to add comments.
   #
+  # Ruby hashes maintain insertion order, so comments render in the order
+  # they were first added. Each location maps to an array of comments,
+  # allowing a class reopened in the same file to accumulate multiple comments.
+  #
   # Before marshalling:
-  # - +comment+ is a String
   # - +location+ is an RDoc::TopLevel
+  # - +comments+ are Strings
   #
   # After unmarshalling:
-  # - +comment+ is an RDoc::Markup::Document
   # - +location+ is a filename String
-  #
-  # These type changes are acceptable (for now) because:
-  # - +comment+: Both String and Document respond to #empty?, and #parse
-  #   returns Document as-is (see RDoc::Text#parse)
-  # - +location+: Only used by #parse to set Document#file, which accepts
-  #   both TopLevel (extracts relative_name) and String
+  # - +comments+ are RDoc::Markup::Documents
 
   attr_accessor :comment_location
 
@@ -63,8 +61,8 @@ class RDoc::ClassModule < RDoc::Context
   def self.from_module(class_type, mod)
     klass = class_type.new mod.name
 
-    mod.comment_location.each do |comment, location|
-      klass.add_comment comment, location
+    mod.comment_location.each do |location, comments|
+      comments.each { |comment| klass.add_comment comment, location }
     end
 
     klass.parent = mod.parent
@@ -125,7 +123,7 @@ class RDoc::ClassModule < RDoc::Context
     @is_alias_for     = nil
     @name             = name
     @superclass       = superclass
-    @comment_location = [] # Array of [comment, location] pairs
+    @comment_location = {} # Hash of { location => [comments] }
 
     super()
   end
@@ -147,11 +145,7 @@ class RDoc::ClassModule < RDoc::Context
                 normalize_comment comment
               end
 
-    if location.parser == RDoc::Parser::C
-      @comment_location.delete_if { |(_, l)| l == location }
-    end
-
-    @comment_location << [comment, location]
+    (@comment_location[location] ||= []) << comment
 
     self.comment = original
   end
@@ -270,7 +264,7 @@ class RDoc::ClassModule < RDoc::Context
   def documented?
     return true if @received_nodoc
     return false if @comment_location.empty?
-    @comment_location.any? { |comment, _| not comment.empty? }
+    @comment_location.each_value.any? { |comments| comments.any? { |c| not c.empty? } }
   end
 
   ##
@@ -411,16 +405,16 @@ class RDoc::ClassModule < RDoc::Context
     @comment    = RDoc::Comment.from_document document
 
     @comment_location = if document.parts.first.is_a?(RDoc::Markup::Document)
-                          document.parts.map { |doc| [doc, doc.file] }
+                          document.parts.group_by(&:file)
                         else
-                          [[document, document.file]]
+                          { document.file => [document] }
                         end
 
     array[5].each do |name, rw, visibility, singleton, file|
       singleton  ||= false
       visibility ||= :public
 
-      attr = RDoc::Attr.new nil, name, rw, nil, singleton: singleton
+      attr = RDoc::Attr.new name, rw, nil, singleton: singleton
 
       add_attribute attr
       attr.visibility = visibility
@@ -447,7 +441,7 @@ class RDoc::ClassModule < RDoc::Context
         @visibility = visibility
 
         methods.each do |name, file|
-          method = RDoc::AnyMethod.new nil, name, singleton: type == 'class'
+          method = RDoc::AnyMethod.new name, singleton: type == 'class'
           method.record_location RDoc::TopLevel.new file
           add_method method
         end
@@ -495,9 +489,9 @@ class RDoc::ClassModule < RDoc::Context
       @comment = RDoc::Comment.from_document(document)
 
       @comment_location = if document.parts.first.is_a?(RDoc::Markup::Document)
-                            document.parts.map { |doc| [doc, doc.file] }
+                            document.parts.group_by(&:file)
                           else
-                            [[document, document.file]]
+                            { document.file => [document] }
                           end
     end
 
@@ -643,11 +637,13 @@ class RDoc::ClassModule < RDoc::Context
     case comment_location
     when String then
       super
-    when Array then
-      docs = comment_location.map do |comment, location|
-        doc = super comment
-        doc.file = location
-        doc
+    when Hash then
+      docs = comment_location.flat_map do |location, comments|
+        comments.map do |comment|
+          doc = super comment
+          doc.file = location
+          doc
+        end
       end
 
       RDoc::Markup::Document.new(*docs)
@@ -677,7 +673,7 @@ class RDoc::ClassModule < RDoc::Context
   # module or class return the name of the latter.
 
   def name_for_path
-    is_alias_for ? is_alias_for.full_name : full_name
+    is_alias_for ? is_alias_for.name_for_path : full_name
   end
 
   ##
@@ -745,12 +741,24 @@ class RDoc::ClassModule < RDoc::Context
   # Returns an HTML snippet of the first comment for search results.
 
   def search_snippet
-    first_comment = @comment_location.first&.first
+    first_comment = @comment_location.each_value.first&.first
     return '' unless first_comment && !first_comment.empty?
 
     snippet(first_comment)
   end
 
+  ##
+  # Rebuilds +@comment+ from the current +@comment_location+ entries,
+  # skipping any empty placeholders.
+
+  def rebuild_comment_from_location
+    texts = @comment_location.each_value.flat_map { |comments|
+      comments.filter_map { |c| c.to_s unless c.empty? }
+    }
+    merged = texts.join("\n---\n")
+    @comment = merged.empty? ? '' : RDoc::Comment.new(merged)
+  end
+
   ##
   # Sets the store for this class or module and its contained code objects.
 
@@ -839,7 +847,16 @@ class RDoc::ClassModule < RDoc::Context
 
   def update_aliases
     constants.each do |const|
-      next unless cm = const.is_alias_for
+      cm = const.is_alias_for
+      cm ||= const.resolved_alias_target if const.is_a?(RDoc::Constant)
+      next unless cm
+
+      # Resolve chained aliases (A = B = C) to the real class/module.
+      cm = @store.find_class_or_module(cm.full_name) || cm
+      while (target = cm.is_alias_for)
+        cm = target
+      end
+
       cm_alias = cm.dup
       cm_alias.name = const.name
 
@@ -851,6 +868,19 @@ class RDoc::ClassModule < RDoc::Context
       end
       cm_alias.full_name = nil # force update for new parent
 
+      # Don't clobber a real (non-alias) class/module already living at this
+      # name. Mirrors the BasicObject = BlankSlate guard in
+      # Context#add_module_alias. Existing alias copies (set by
+      # add_module_alias or a previous update_aliases pass) carry is_alias_for,
+      # so they're still overwritable here.
+      existing = @store.find_class_or_module(cm_alias.full_name)
+      next if existing && !existing.is_alias_for
+
+      # Persist a lazy-resolved target so Stats#report_constants and
+      # Constant#marshal_dump observe the alias relationship. Skipped
+      # aliases (above) intentionally leave the constant unmarked.
+      const.is_alias_for ||= cm
+
       cm_alias.aliases.clear
       cm_alias.is_alias_for = cm
 

data/lib/rdoc/code_object/constant.rb

@@ -26,6 +26,14 @@ class RDoc::Constant < RDoc::CodeObject
 
   attr_accessor :visibility
 
+  ##
+  # The constant path on the RHS when the RHS is a bare constant reference
+  # (+Foo = Bar+ or +Foo = Bar::Baz+). Captured at parse time so
+  # #resolved_alias_target doesn't have to re-derive it from the textual
+  # #value. nil for other RHS shapes.
+
+  attr_accessor :is_alias_for_path
+
   ##
   # Creates a new constant with +name+, +value+ and +comment+
 
@@ -35,8 +43,9 @@ class RDoc::Constant < RDoc::CodeObject
     @name  = name
     @value = value
 
-    @is_alias_for = nil
-    @visibility   = :public
+    @is_alias_for      = nil
+    @is_alias_for_path = nil
+    @visibility        = :public
 
     self.comment = comment
   end
@@ -83,7 +92,10 @@ class RDoc::Constant < RDoc::CodeObject
   end
 
   ##
-  # The module or class this constant is an alias for
+  # The module or class this constant is an alias for, when one was recorded
+  # explicitly (by RDoc::Context#add_module_alias, RDoc::ClassModule#update_aliases,
+  # or ri marshal load). Pure accessor; see #resolved_alias_target for the
+  # opportunistic lookup path.
 
   def is_alias_for
     case @is_alias_for
@@ -96,6 +108,20 @@ class RDoc::Constant < RDoc::CodeObject
     end
   end
 
+  ##
+  # Returns the class/module this constant *would* alias if #is_alias_for_path
+  # was set by the parser and that path resolves to a known class/module, or
+  # nil. Used to support `Const = RHS` parsed before `class RHS;end` is defined
+  # in another file. Pure lookup; does not mutate state. Honors :nodoc:
+  # (returns nil if document_self is false). Note that module nesting
+  # information is lost, so constant lookup is inaccurate.
+
+  def resolved_alias_target
+    return nil unless document_self
+    return nil unless @is_alias_for_path
+    parent.find_module_named(@is_alias_for_path)
+  end
+
   def inspect # :nodoc:
     "#<%s:0x%x %s::%s>" % [
       self.class, object_id,