rdoc 6.14.2 → 7.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff34d02bfaa6b5e36bd3ab29b6fdfc10e41a50ba0fbef3841aed3e59d22e8d29
-  data.tar.gz: bee9f682708babef768b5fe0b5b68a505ad09ba255c20c00fdefb52cd5135566
+  metadata.gz: e115c57c1541a612613ea80a869ce964b13aee43badba6c75bae66aa70495e29
+  data.tar.gz: 5a0dfd61dc9a5116612d939f3d94197fe687667cd8185d00983afb3fea38aade
 SHA512:
-  metadata.gz: 10729c09826000d5ac6d4137fdba80b36dd7da96c66475ee03fcfe527dd159a74f41ec8c1a5cb588373c4007ea02a18cd9ca5e09e1766125daab7e84ca17a6ae
-  data.tar.gz: 785c69b91032d0e72810f91c56271d100d03439355bda96f808faaea60ec2768caab376a8420bbbb72e7bbeb6c50a06ed5a002c668342aa80444ee7d0b1c2a6f
+  metadata.gz: fc7d789798d547865d5205eafbb6b8db9b5b16bc422c5fba3658952a8568248eda44aba606c1c1cac335af38babdf18bf4a2aa56f1c7189fe894858e154c9353
+  data.tar.gz: da731f564307246734edefbc271577d434b3d4527d865cd2c6575db5dce5d36caab97925204bacbb1a2063aff4109a55db5c269829df32e5ac29163b366b8c7d

data/CONTRIBUTING.md

@@ -0,0 +1,196 @@
+# Contributing to RDoc
+
+Thank you for your interest in contributing to RDoc! This document provides guidelines and instructions for contributing.
+
+## Reporting Bugs
+
+If you think you found a bug, open an issue on the [issue tracker](https://github.com/ruby/rdoc/issues) on GitHub.
+
+When reporting a bug:
+
+- Include a sample file that illustrates the problem, or link to the repository/gem associated with the bug
+- Include steps to reproduce the issue
+
+## Development Setup
+
+RDoc uses Bundler for development. To get started:
+
+```bash
+bundle install
+bundle exec rake
+```
+
+This will install dependencies and run the tests.
+
+If you're working on CSS or templates, you'll also want Node dependencies for the CSS linter:
+
+```bash
+npm install
+```
+
+If 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.
+
+**Note:** Generated parser files are committed to the repository. If you delete them (for example via `bundle exec rake clean`) or you change any `.ry`/`.kpeg` parser sources, run `bundle exec rake generate` before running tests.
+
+## Running Tests
+
+```bash
+# Run all tests (default task)
+bundle exec rake
+
+# Run unit tests only (excludes RubyGems integration)
+bundle exec rake normal_test
+
+# Run RubyGems integration tests only
+bundle exec rake rubygems_test
+
+# Verify generated parser files are current (CI check)
+bundle exec rake verify_generated
+```
+
+- **Test Framework:** [`test-unit`](https://github.com/test-unit/test-unit)
+- **Test Location:** `test/` directory
+- **Test Helper:** `test/lib/helper.rb`
+
+## Linting
+
+### RuboCop (Ruby Code)
+
+```bash
+# Check Ruby code style
+bundle exec rubocop
+
+# Auto-fix style issues
+bundle exec rubocop -A
+```
+
+### Herb Linter (ERB/RHTML Templates)
+
+```bash
+# Lint ERB template files
+npx @herb-tools/linter "**/*.rhtml"
+
+# Lint specific directory
+npx @herb-tools/linter "lib/**/*.rhtml"
+```
+
+**Template Location:** `lib/rdoc/generator/template/**/*.rhtml`
+
+### Stylelint (CSS Files)
+
+```bash
+# Lint CSS files
+npm run lint:css
+
+# Auto-fix style issues
+npm run lint:css -- --fix
+```
+
+## Type annotations
+
+RDoc is currently not a typed codebase. Despite not running a type checker, contributors have been
+adding some comment annotations to make the codebase easier to navigate and understand.
+
+These annotations use [Sorbet flavored RBS](https://sorbet.org/docs/rbs-support) annotations,
+so that we can tag definitions as abstract and override. For more information on RBS syntax,
+see the [documentation](https://github.com/ruby/rbs/blob/master/docs/syntax.md).
+
+## Parser Generation
+
+RDoc uses generated parsers for Markdown and RD formats.
+
+```bash
+# Generate all parser files from sources
+bundle exec rake generate
+
+# Remove generated parser files
+bundle exec rake clean
+
+# Verify generated files are in sync with sources (CI check)
+bundle exec rake verify_generated
+```
+
+**Source Files** (edit these):
+
+- `lib/rdoc/rd/block_parser.ry` → generates `block_parser.rb` via racc
+- `lib/rdoc/rd/inline_parser.ry` → generates `inline_parser.rb` via racc
+- `lib/rdoc/markdown.kpeg` → generates `markdown.rb` via kpeg
+- `lib/rdoc/markdown/literals.kpeg` → generates `literals.rb` via kpeg
+
+**Important:**
+
+- Generated parser files **should be committed** to the repository
+- Do not edit generated `.rb` parser files directly
+- After modifying `.ry` or `.kpeg` source files, run `bundle exec rake generate`
+- CI runs `rake verify_generated` to ensure generated files are in sync with their sources
+
+## Documentation Generation
+
+```bash
+# Generate documentation (creates _site directory)
+bundle exec rake rdoc
+
+# Force regenerate documentation
+bundle exec rake rerdoc
+
+# Show documentation coverage
+bundle exec rake rdoc:coverage
+bundle exec rake coverage
+```
+
+- **Output Directory:** `_site/` (GitHub Pages compatible)
+- **Configuration:** `.rdoc_options` and `.document`
+
+## Themes
+
+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
+
+New feature development should focus on the Aliki theme. Darkfish will continue to receive bug fixes but no new features.
+
+Theme templates are located at `lib/rdoc/generator/template/<theme>/`.
+
+## Project Structure
+
+```
+lib/rdoc/
+├── rdoc.rb                    # Main entry point (RDoc::RDoc class)
+├── version.rb                 # Version constant
+├── task.rb                    # Rake task integration
+├── parser/                    # Source code parsers
+│   ├── ruby.rb                # Ruby code 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)
+│   ├── markup.rb              # Markup format generator
+│   ├── ri.rb                  # RI command generator
+│   └── template/              # ERB templates
+│       ├── aliki/             # Aliki theme (default)
+│       └── darkfish/          # Darkfish theme (deprecated)
+├── markup/                    # Markup parsing and formatting
+├── code_object/               # AST objects for documented items
+├── markdown.kpeg              # Parser source (edit this)
+├── markdown.rb                # Generated parser (do not edit)
+├── markdown/                  # Markdown parsing
+│   ├── literals.kpeg          # Parser source (edit this)
+│   └── literals.rb            # Generated parser (do not edit)
+├── rd/                        # RD format parsing
+│   ├── block_parser.ry        # Parser source (edit this)
+│   ├── block_parser.rb        # Generated parser (do not edit)
+│   ├── inline_parser.ry       # Parser source (edit this)
+│   └── inline_parser.rb       # Generated parser (do not edit)
+└── ri/                        # RI (Ruby Info) tool
+
+test/                          # Test files
+├── lib/helper.rb              # Test helpers
+└── rdoc/                      # Main test directory
+```
+
+## Code of Conduct
+
+Please be respectful and constructive in all interactions. We're all here to make RDoc better!

data/History.rdoc

@@ -163,7 +163,7 @@
   * Moved old DEVELOPERS file to CONTRIBUTING to match github conventions.
   * TomDoc output now has a "Returns" heading.  Issue #234 by Brian Henderson
   * Metaprogrammed methods can now use the :args: directive in addition to the
-    :call-seq: directive.  Issue #236 by Mike Moore.
+    \:call-seq: directive.  Issue #236 by Mike Moore.
   * Sections can be linked to using "@" like labels.  If a section and a label
     have the same name the section will be preferred.  Issue #233 by Brian
     Henderson.

data/LEGAL.rdoc

@@ -4,6 +4,12 @@
 
 The files in this distribution are covered by the Ruby license (see LICENSE) except the features mentioned below:
 
+Aliki::
+  Aliki was written by Stan Lo and is included under the MIT license.
+
+  * lib/rdoc/generator/aliki.rb
+  * lib/rdoc/generator/template/aliki/*
+
 Darkfish::
   Darkfish was written by Michael Granger and is included under the BSD 3-Clause
   license.  Darkfish contains images from the Silk Icons set by Mark James.

data/README.md

@@ -0,0 +1,129 @@
+# RDoc - Ruby Documentation System
+
+- GitHub: [https://github.com/ruby/rdoc](https://github.com/ruby/rdoc)
+- Issues: [https://github.com/ruby/rdoc/issues](https://github.com/ruby/rdoc/issues)
+
+## 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.
+
+## Generating Documentation
+
+Once installed, you can create documentation using the `rdoc` command
+
+```shell
+rdoc [options] [names...]
+```
+
+For an up-to-date option summary, type
+
+```shell
+rdoc --help
+```
+
+A typical use might be to generate documentation for a package of Ruby source (such as RDoc itself).
+
+```shell
+rdoc
+```
+
+This command generates documentation for all the Ruby and C source files in and below the current directory.  These will be stored in a documentation tree starting in the subdirectory `doc`.
+
+You can make this slightly more useful for your readers by having the index page contain the documentation for the primary file.  In our case, we could type
+
+```shell
+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.
+
+To generate documentation using `rake` see [RDoc::Task](https://ruby.github.io/rdoc/RDoc/Task.html).
+
+To generate documentation programmatically:
+
+```rb
+require 'rdoc/rdoc'
+
+options = RDoc::Options.new
+options.files = ['a.rb', 'b.rb']
+options.setup_generator 'aliki'
+# see RDoc::Options
+
+rdoc = RDoc::RDoc.new
+rdoc.document options
+# see RDoc::RDoc
+```
+
+You can specify the target files for document generation with `.document` file in the project root directory. `.document` file contains a list of file and directory names including comment lines starting with `#`. See [https://github.com/ruby/rdoc/blob/master/.document](https://github.com/ruby/rdoc/blob/master/.document) as an example.
+
+## Writing Documentation
+
+To write documentation for RDoc place a comment above the class, module, method, constant, or attribute you want documented:
+
+```rb
+##
+# This class represents an arbitrary shape by a series of points.
+class Shape
+  ##
+  # Creates a new shape described by a +polyline+.
+  #
+  # If the +polyline+ does not end at the same point it started at the
+  # first pointed is copied and placed at the end of the line.
+  #
+  # An ArgumentError is raised if the line crosses itself, but shapes may
+  # be concave.
+  def initialize polyline
+    # ...
+  end
+end
+```
+
+The default comment markup format is the RDoc::Markup format. TomDoc, Markdown and RD format comments are also supported.  You can set the default comment format for your entire project by creating a `.rdoc_options` file.  See RDoc::Options@Saved+Options for instructions on creating one.  You can also set the comment format for a single file through the `:markup:` directive, but this is only recommended if you wish to switch markup formats.  See RDoc::Markup@Other+directives.
+
+Comments can contain directives that tell RDoc information that it cannot otherwise discover through parsing.  See RDoc::Markup@Directives to control what is or is not documented, to define method arguments or to break up methods in a class by topic.  See RDoc::Parser::Ruby for directives used to teach RDoc about metaprogrammed methods.
+
+See RDoc::Parser::C for documenting C extensions with RDoc.
+
+To determine how well your project is documented run `rdoc -C lib` to get a documentation coverage report.  `rdoc -C1 lib` includes parameter names in the documentation coverage report.
+
+## Theme Options
+
+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
+
+To use the Darkfish theme instead of the default Aliki theme:
+
+```shell
+rdoc --format darkfish
+```
+
+Or in your `.rdoc_options` file:
+
+```yaml
+generator_name: darkfish
+```
+
+There are also a few community-maintained themes for RDoc:
+
+- [rorvswild-theme-rdoc](https://github.com/BaseSecrete/rorvswild-theme-rdoc)
+- [hanna](https://github.com/jeremyevans/hanna) (a fork maintained by [Jeremy Evans](https://github.com/jeremyevans))
+
+Please follow the theme's README for usage instructions.
+
+## 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.
+
+## License
+
+RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers. Portions (c) 2007-2011 Eric Hodel.  Portions copyright others, see individual files and LEGAL.rdoc for details.
+
+RDoc is free software, and may be redistributed under the terms specified in LICENSE.rdoc.
+
+## Warranty
+
+This software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantability and fitness for a particular purpose.

data/RI.md

@@ -48,7 +48,7 @@ the [Ruby online documentation](https://docs.ruby-lang.org/en/master):
 - If you are working in a terminal window, typing `ri _whatever_` (or just `ri`)
   may be faster than navigating to a browser window and searching for documentation.
 - If you are working in an
-  [irb \(interactive Ruby\)](https://docs.ruby-lang.org/en/master/IRB.html)
+  [irb \(interactive Ruby\)](https://ruby.github.io/irb/index.html)
   session, you _already_ have immediate access to `ri`:
   just type `'show_doc'`.
 

data/lib/rdoc/code_object/any_method.rb

@@ -351,7 +351,6 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     return call_seq unless is_alias_for || !aliases.empty?
 
     method_name = self.name
-    method_name = method_name[0, 1] if method_name =~ /\A\[/
 
     entries = call_seq.split "\n"
 
@@ -360,15 +359,24 @@ class RDoc::AnyMethod < RDoc::MethodAttr
       ignore << is_alias_for.name
       ignore.concat is_alias_for.aliases.map(&:name)
     end
-    ignore.map! { |n| n =~ /\A\[/ ? /\[.*\]/ : n}
+
     ignore.delete(method_name)
-    ignore = Regexp.union(ignore)
+    ignore_bracket_methods, ignore_other_methods = ignore.partition {|i| i.start_with?('[') }
 
-    matching = entries.reject do |entry|
-      entry =~ /^\w*\.?#{ignore}[$\(\s]/ or
-        entry =~ /\s#{ignore}\s/
+    if ignore_other_methods.any?
+      ignore_union = Regexp.union(ignore_other_methods)
+      entries.reject! do |entry|
+        /\A(?:\w*\.)?#{ignore_union}(?:[(\s]|\z)/.match?(entry) ||
+          /\s#{ignore_union}\s/.match?(entry)
+      end
+    end
+    if ignore_bracket_methods.any?
+      entries.reject! do |entry|
+        # Ignore `receiver[arg] -> return_type` `[](arg)` `[]`
+        /\A\w*\[.*?\](?:[(\s]|\z)/.match?(entry)
+      end
     end
 
-    matching.empty? ? nil : matching.join("\n")
+    entries.empty? ? nil : entries.join("\n")
   end
 end

data/lib/rdoc/code_object/class_module.rb

@@ -30,7 +30,22 @@ class RDoc::ClassModule < RDoc::Context
   attr_accessor :constant_aliases
 
   ##
-  # Comment and the location it came from.  Use #add_comment to add comments
+  # An array of `[comment, location]` pairs documenting this class/module.
+  # Use #add_comment to add comments.
+  #
+  # Before marshalling:
+  # - +comment+ is a String
+  # - +location+ is an RDoc::TopLevel
+  #
+  # 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
 
   attr_accessor :comment_location
 
@@ -110,7 +125,7 @@ class RDoc::ClassModule < RDoc::Context
     @is_alias_for     = nil
     @name             = name
     @superclass       = superclass
-    @comment_location = [] # [[comment, location]]
+    @comment_location = [] # Array of [comment, location] pairs
 
     super()
   end
@@ -379,10 +394,10 @@ class RDoc::ClassModule < RDoc::Context
 
     @comment    = RDoc::Comment.from_document document
 
-    @comment_location = if RDoc::Markup::Document === document.parts.first then
-                          document
+    @comment_location = if document.parts.first.is_a?(RDoc::Markup::Document)
+                          document.parts.map { |doc| [doc, doc.file] }
                         else
-                          RDoc::Markup::Document.new document
+                          [[document, document.file]]
                         end
 
     array[5].each do |name, rw, visibility, singleton, file|
@@ -689,6 +704,9 @@ class RDoc::ClassModule < RDoc::Context
 
   ##
   # Search record used by RDoc::Generator::JsonIndex
+  #
+  # TODO: Remove this method after dropping the darkfish theme and JsonIndex generator.
+  # Use #search_snippet instead for getting documentation snippets.
 
   def search_record
     [
@@ -702,6 +720,16 @@ class RDoc::ClassModule < RDoc::Context
     ]
   end
 
+  ##
+  # Returns an HTML snippet of the first comment for search results.
+
+  def search_snippet
+    first_comment = @comment_location.first&.first
+    return '' unless first_comment && !first_comment.empty?
+
+    snippet(first_comment)
+  end
+
   ##
   # Sets the store for this class or module and its contained code objects.
 
@@ -794,11 +822,13 @@ class RDoc::ClassModule < RDoc::Context
       cm_alias = cm.dup
       cm_alias.name = const.name
 
-      # Don't move top-level aliases under Object, they look ugly there
-      unless RDoc::TopLevel === cm_alias.parent then
+      if full_name == 'Object'
+        # Don't move top-level aliases under Object, they look ugly there
+        cm_alias.parent = top_level
+      else
         cm_alias.parent = self
-        cm_alias.full_name = nil # force update for new parent
       end
+      cm_alias.full_name = nil # force update for new parent
 
       cm_alias.aliases.clear
       cm_alias.is_alias_for = cm

data/lib/rdoc/code_object/constant.rb

@@ -154,6 +154,15 @@ class RDoc::Constant < RDoc::CodeObject
     "#{@parent.path}##{@name}"
   end
 
+  ##
+  # Returns an HTML snippet of the comment for search results.
+
+  def search_snippet
+    return '' if comment.empty?
+
+    snippet(comment)
+  end
+
   def pretty_print(q) # :nodoc:
     q.group 2, "[#{self.class.name} #{full_name}", "]" do
       unless comment.empty? then

data/lib/rdoc/code_object/method_attr.rb

@@ -375,6 +375,9 @@ class RDoc::MethodAttr < RDoc::CodeObject
   ##
   # Used by RDoc::Generator::JsonIndex to create a record for the search
   # engine.
+  #
+  # TODO: Remove this method after dropping the darkfish theme and JsonIndex generator.
+  # Use #search_snippet instead for getting documentation snippets.
 
   def search_record
     [
@@ -384,10 +387,19 @@ class RDoc::MethodAttr < RDoc::CodeObject
       @parent.full_name,
       path,
       params,
-      snippet(@comment),
+      search_snippet,
     ]
   end
 
+  ##
+  # Returns an HTML snippet of the comment for search results.
+
+  def search_snippet
+    return '' if @comment.empty?
+
+    snippet(@comment)
+  end
+
   def to_s # :nodoc:
     if @is_alias_for
       "#{self.class.name}: #{full_name} -> #{is_alias_for}"

data/lib/rdoc/code_object/top_level.rb

@@ -16,6 +16,16 @@ class RDoc::TopLevel < RDoc::Context
 
   attr_accessor :absolute_name
 
+  ##
+  # Base name of this file
+
+  attr_reader :base_name
+
+  ##
+  # Base name of this file without the extension
+
+  attr_reader :page_name
+
   ##
   # All the classes or modules that were declared in
   # this file. These are assigned to either +#classes_hash+
@@ -40,6 +50,14 @@ class RDoc::TopLevel < RDoc::Context
     @relative_name = relative_name
     @parser        = nil
 
+    if relative_name
+      @base_name = File.basename(relative_name)
+      @page_name = @base_name.sub(/\.(rb|rdoc|txt|md)\z/i, '')
+    else
+      @base_name = nil
+      @page_name = nil
+    end
+
     @classes_or_modules = []
   end
 
@@ -105,23 +123,8 @@ class RDoc::TopLevel < RDoc::Context
     @classes_or_modules << mod
   end
 
-  ##
-  # Base name of this file
-
-  def base_name
-    File.basename @relative_name
-  end
-
   alias name base_name
 
-  ##
-  # Only a TopLevel that contains text file) will be displayed.  See also
-  # RDoc::CodeObject#display?
-
-  def display?
-    text? and super
-  end
-
   ##
   # See RDoc::TopLevel::find_class_or_module
   #--
@@ -212,16 +215,6 @@ class RDoc::TopLevel < RDoc::Context
     end
   end
 
-  ##
-  # Base name of this file without the extension
-
-  def page_name
-    basename = File.basename @relative_name
-    basename =~ /\.(rb|rdoc|txt|md)$/i
-
-    $` || basename
-  end
-
   ##
   # Path to this file for use with HTML generator output.
 
@@ -244,6 +237,9 @@ class RDoc::TopLevel < RDoc::Context
 
   ##
   # Search record used by RDoc::Generator::JsonIndex
+  #
+  # TODO: Remove this method after dropping the darkfish theme and JsonIndex generator.
+  # Use #search_snippet instead for getting documentation snippets.
 
   def search_record
     return unless @parser < RDoc::Parser::Text
@@ -255,10 +251,19 @@ class RDoc::TopLevel < RDoc::Context
       '',
       path,
       '',
-      snippet(@comment),
+      search_snippet,
     ]
   end
 
+  ##
+  # Returns an HTML snippet of the comment for search results.
+
+  def search_snippet
+    return '' if @comment.empty?
+
+    snippet(@comment)
+  end
+
   ##
   # Is this TopLevel from a text file instead of a source code file?