Display RBS type signatures in documentation by st0012 · Pull Request #1665 · ruby/rdoc

st0012 · 2026-03-30T16:09:58Z

Summary

Display RBS type signatures in HTML documentation and RI terminal output
Source type information from inline #: annotations and .rbs files (including RBS stdlib)
Link type names in signatures to their documentation pages

Details

New module: RDoc::RbsHelper

Loads RBS signatures from sig/ directories and stdlib declarations via RBS::EnvironmentLoader
Validates inline #: annotations using RBS::Parser, warns with file:line on invalid signatures
Renders type signatures as HTML with type names linked to their documentation pages using a.rbs-type

Parser integration (PrismRuby)

Extracts #: annotation lines from comments via RBS_SIG_LINE constant
Attaches parsed type signatures to MethodAttr#type_signature_lines
Inline annotations take priority over .rbs file signatures

Store

merge_rbs_signatures fills in type signatures from loaded .rbs files where no inline annotation exists
type_name_lookup builds a cached name-to-path map for type linking; ambiguous unqualified names are excluded to avoid wrong links

Display

Aliki theme: method signatures render as styled <pre> blocks with dotted separator; attribute signatures render inline after the [RW] badge
RI driver: type signatures display as verbatim blocks after argument lists
JS updated to exclude type signature blocks from copy-button wrapping

Serialization

MARSHAL_VERSION bumped to 4 for both AnyMethod and Attr (additive — appends type_signature_lines to marshal array)

CI/Dependencies

Minimum Ruby bumped to 3.2 (required by rbs 4.0)
Added rbs >= 4.0.0 and prism >= 1.6.0 dependencies
Dropped JRuby from CI matrix (rbs has a C extension); TruffleRuby retained (verified working)

matzbot · 2026-03-30T16:11:14Z

🚀 Preview deployment available at: https://7770c6cf.rdoc-6cd.pages.dev (commit: 7b82009)

Copilot

Pull request overview

This PR adds first-class support for RBS type signatures in RDoc by extracting inline #: annotations during parsing, optionally loading signatures from .rbs files, and rendering those signatures in both HTML (Aliki theme) and ri terminal output.

Changes:

Extract #: type signatures from comment blocks in the Prism parser and attach them to RDoc::MethodAttr objects.
Load/merge signatures from RBS sources into the store (without overwriting inline annotations) and add type-name linking in HTML output.
Render signatures in Aliki HTML + ri, update marshal formats, and bump runtime requirements (Ruby >= 3.2, add rbs dependency).

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
`lib/rdoc/parser/prism_ruby.rb`	Extracts/validates inline `#:` signatures and attaches them to methods/attrs.
`lib/rdoc/rbs_support.rb`	New RBS integration: validation, signature loading, and HTML linking.
`lib/rdoc/store.rb`	Adds signature merge logic and cached type-name lookup for linking.
`lib/rdoc/generator/aliki.rb`	Exposes `type_signature_html` helper for templates (linked type names).
`lib/rdoc/generator/template/aliki/class.rhtml`	Renders type signatures for methods and attributes in HTML output.
`lib/rdoc/generator/template/aliki/css/rdoc.css`	Styles signature blocks and linked type names.
`lib/rdoc/generator/template/aliki/js/aliki.js`	Avoids wrapping signature `<pre>` blocks with “copy” UI.
`lib/rdoc/ri/driver.rb`	Prints method type signatures in `ri` output.
`lib/rdoc/code_object/method_attr.rb`	Adds `type_signature` storage + line splitting helper.
`lib/rdoc/code_object/any_method.rb`	Bumps marshal version and persists `type_signature`.
`lib/rdoc/code_object/attr.rb`	Bumps marshal version and persists `type_signature`.
`lib/rdoc/rdoc.rb`	Loads RBS signatures after store completion and merges into objects.
`rdoc.gemspec`	Bumps Ruby minimum to 3.2, adds `rbs` dependency, bumps `prism` minimum.
`Gemfile`	Always includes `mini_racer` on MRI (Ruby >= 3.2 now required).
`.github/workflows/test.yml`	Aligns CI with Ruby >= 3.2 and updated Prism versions.
`test/rdoc/parser/prism_ruby_test.rb`	Adds Prism-only tests for inline signature extraction.
`test/rdoc/rbs_support_test.rb`	New tests for validation, loading, and HTML linking.
`test/rdoc/rdoc_store_test.rb`	Tests signature merging + `type_name_lookup` behavior/caching.
`test/rdoc/ri/driver_test.rb`	Tests `ri` output includes a type signature.
`test/rdoc/code_object/any_method_test.rb`	Tests marshal persistence for method type signatures.
`test/rdoc/code_object/attr_test.rb`	Tests marshal persistence for attribute type signatures.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

skatkov · 2026-04-12T19:49:49Z

Do I understand correctly that the sorbet type signature will not work with this implementation?

st0012 · 2026-04-12T20:07:43Z

Yes, because it's not a official signature syntax for Ruby.

kou · 2026-04-12T21:07:27Z

Dropped JRuby/TruffleRuby from CI matrix (rbs has a C extension)

Does this mean that JRuby can't use RDoc with this?

st0012 · 2026-04-12T21:31:27Z

@kou Unfortunately, yes. It's essentially a decision between:

Having rbs as an official dependency with proper version restriction in gemspec, but JRuby won't be supported until it supports rbs
Having rbs as a soft dependency and bail when rbs version doesn't match.
- Note that with this approach, if a project runs RDoc with bundle exec, rbs needs to be added in the bundle manually/by other gems too

Given that I want to make RBS support a key feature of future RDoc and directly encourage gems to write more RBS signatures, I think 1 is a more reasonable decision.

st0012 · 2026-04-12T22:22:21Z

@headius I assumed JRuby doesn't support rbs 4.0+ due to this failure. Is it true that it's not supported? Or I can actually just tweak the CI config to make it work.

Add `rbs` and its dependency `logger` to the bundled gem load paths in `tool/rdoc-srcdir`, and add the compiled extension path from `.bundle/extensions/` so the `rbs_extension` C extension can be found. This is needed because `make html` runs with `--disable-gems`, so RubyGems cannot resolve the extension path automatically. The extension is already compiled by `make build-ext` (which `make html` depends on via `main`), it just wasn't discoverable. Required for ruby/rdoc#1665 to work with `make html` in ruby/ruby.

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

RBS 4.0 requires Ruby >= 3.2. Bump RDoc's own minimum to match and add `rbs >= 4.0.0` as a gemspec dependency. Bump prism minimum to `>= 1.6.0` (required by rbs). Drop JRuby from CI matrix (rbs has a C extension that cannot build on it).

Add support for displaying RBS type signatures in both HTML and RI output. Type information is sourced from inline `#:` annotations (parsed by the Prism parser) and from `.rbs` files in the project's `sig/` directory plus RBS stdlib declarations. Implementation: - `RDoc::RbsHelper` module: loads RBS signatures, validates types, renders type signatures as HTML with linked type names - Parser extracts `#:` annotation lines via `RBS_SIG_LINE` constant, validates them, and attaches to `MethodAttr#type_signature` - `Store#merge_rbs_signatures` fills in signatures from `.rbs` files where inline annotations are absent - `Store#type_name_lookup` maps qualified and unambiguous unqualified names to documentation paths for type linking - Aliki theme: type signatures render as styled `<pre>` blocks under method headings, with linked type names using `a.rbs-type` class - RI driver: type signatures display as verbatim blocks - `MARSHAL_VERSION` bumped to 4 for `AnyMethod` and `Attr`

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Skipping the ambiguity check when `cm.name == cm.full_name` let a nested class (e.g. `Gem::SafeMarshal::Elements::String`) register itself as the unqualified `String` in `unqualified_names`, which then overwrote the core `String` entry during the final `lookup.merge!`. Remove the skip so top-level classes participate in ambiguity detection — the second sighting now correctly marks the name ambiguous and deletes it from `unqualified_names`, leaving `lookup["String"]` pointing at the core class's path.

…n attr keys Three fixes for `merge_rbs_signatures` and the surrounding freshness flow: - `rdoc.rb` now records `sig/*.rbs` mtimes alongside Ruby files in `@last_modified` and forces a full reparse when only signatures changed. The cached HTML pipeline keeps no in-memory class data across runs, so without this `merge_rbs_signatures` would run on an empty store. Also surfaces `rbs_signature_files`/`watch_files` for the live server's watcher. - `store.rb` now propagates merged RBS signatures to aliases immediately during assignment by walking `method_attr.aliases`, and tracks assigned objects so a re-merge in the live-server reload path can clear stale signatures without nuking inline `#:` annotations. - `rbs_helper.rb` keys singleton attributes as `Klass.attr` and instance attributes as `Klass#attr`, mirroring the method key format and preventing a singleton attr from clobbering an instance attr (or vice versa) when both share a name. Drive-by cleanups while in the area: fold `.rbs` into `remove_unparseable`'s extension regex; collapse the two identical `rbs_*_key` helpers into one `rbs_key`; drop a redundant `File.directory?` guard before `Dir[]`.

…tale clearing Three small fixes around `load_rbs_signatures` and the helper that walks RBS declarations: - `rbs_helper.rb` now emits both `Class.foo` and `Class#foo` keys when an RBS member's kind is `:singleton_instance` (i.e. `def self?.foo`). RDoc generates both a singleton and a private instance method for module-function-style definitions, so the previous singleton-only key left the instance method without type signature lines. - `rdoc.rb` widens the rescue in `load_rbs_signatures` from `RBS::ParsingError` to `RBS::BaseError`. Loader-level failures (duplicate declarations, generic-arity mismatches, etc.) inherit from `RBS::BaseError` / `RBS::LoadingError` rather than `ParsingError`, so they previously aborted documentation generation instead of warning and continuing. - `rdoc.rb` also calls `@store.clear_rbs_signatures` in the rescue. In server mode a previous successful load may have populated the long-lived store; without clearing, a now-broken sig file leaves stale `type_signature_lines` showing on regenerated pages alongside the warning.

Copilot

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated 2 comments.

st0012 force-pushed the integrate-rbs branch from 22931f5 to 2fecc01 Compare March 30, 2026 17:11

st0012 added the enhancement label Mar 30, 2026

st0012 force-pushed the integrate-rbs branch from 9c63b36 to 736198f Compare April 2, 2026 17:28

st0012 changed the base branch from master to signature-card-design April 2, 2026 17:29

st0012 force-pushed the integrate-rbs branch from 736198f to b161892 Compare April 2, 2026 17:44

st0012 force-pushed the signature-card-design branch from 251f5db to be86678 Compare April 2, 2026 18:05

st0012 force-pushed the integrate-rbs branch 4 times, most recently from a469122 to bfcd437 Compare April 2, 2026 22:17

st0012 force-pushed the signature-card-design branch from be86678 to 4b26c40 Compare April 9, 2026 14:54

Base automatically changed from signature-card-design to master April 9, 2026 15:04

st0012 force-pushed the integrate-rbs branch from bfcd437 to 25103b6 Compare April 9, 2026 19:51

st0012 requested a review from Copilot April 9, 2026 19:51

Copilot started reviewing on behalf of st0012 April 9, 2026 19:52 View session

Copilot AI reviewed Apr 9, 2026

View reviewed changes

st0012 force-pushed the integrate-rbs branch 2 times, most recently from 599eacc to 1034e9b Compare April 10, 2026 18:15

st0012 marked this pull request as ready for review April 10, 2026 18:32

Copilot AI review requested due to automatic review settings April 10, 2026 18:32

Copilot started reviewing on behalf of st0012 April 10, 2026 18:33 View session

Copilot AI reviewed Apr 10, 2026

View reviewed changes

Comment thread lib/rdoc/parser/prism_ruby.rb Outdated

Comment thread lib/rdoc/parser/prism_ruby.rb Outdated

Comment thread lib/rdoc/rbs_helper.rb

st0012 force-pushed the integrate-rbs branch from 1034e9b to fd4b149 Compare April 12, 2026 18:41

st0012 force-pushed the integrate-rbs branch from bace941 to f814d75 Compare April 17, 2026 13:47

st0012 requested a review from Copilot April 18, 2026 14:07

Copilot started reviewing on behalf of st0012 April 18, 2026 14:08 View session

Copilot AI reviewed Apr 18, 2026

View reviewed changes

Comment thread lib/rdoc/parser/ruby.rb

Comment thread lib/rdoc/rbs_helper.rb

Comment thread lib/rdoc/store.rb

st0012 force-pushed the integrate-rbs branch from f814d75 to 0c566bc Compare April 19, 2026 06:58

st0012 requested a review from Copilot April 19, 2026 11:55

Copilot started reviewing on behalf of st0012 April 19, 2026 11:55 View session

Copilot AI reviewed Apr 19, 2026

View reviewed changes

Comment thread lib/rdoc/parser/prism_ruby.rb Outdated

Comment thread lib/rdoc/rdoc.rb

Comment thread lib/rdoc/rbs_helper.rb

st0012 force-pushed the integrate-rbs branch from 0c566bc to f88c11e Compare April 21, 2026 06:53

Copilot AI review requested due to automatic review settings April 21, 2026 07:34

st0012 force-pushed the integrate-rbs branch from f88c11e to 0b6d9fa Compare April 21, 2026 07:34

Copilot started reviewing on behalf of st0012 April 21, 2026 07:34 View session

Copilot AI reviewed Apr 21, 2026

View reviewed changes

Comment thread lib/rdoc/parser/ruby.rb

Comment thread lib/rdoc/rbs_helper.rb Outdated

Comment thread lib/rdoc/parser/prism_ruby.rb Outdated

Copilot AI review requested due to automatic review settings April 21, 2026 07:40

Copilot started reviewing on behalf of st0012 April 21, 2026 07:40 View session

Copilot AI reviewed Apr 21, 2026

View reviewed changes

Comment thread lib/rdoc/rbs_helper.rb

Comment thread lib/rdoc/rbs_helper.rb Outdated

Comment thread Gemfile

Comment thread lib/rdoc/parser/ruby.rb

Comment thread lib/rdoc/parser/ruby.rb

Comment thread lib/rdoc/store.rb Outdated

st0012 mentioned this pull request Apr 26, 2026

Incompatibility with rdoc 7.2.0 and ruby 2.6 #1683

Closed

This was referenced Apr 28, 2026

Support rbs types skatkov/rdoc-markdown#50

Open

Support sorbet's sig skatkov/rdoc-markdown#38

Open

st0012 and others added 7 commits May 7, 2026 13:34

Potential fix for pull request finding

62c5d3a

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

78f9da0

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings May 7, 2026 07:21

st0012 force-pushed the integrate-rbs branch from 1862485 to 7b82009 Compare May 7, 2026 07:21

Copilot started reviewing on behalf of st0012 May 7, 2026 07:22 View session

Copilot AI reviewed May 7, 2026

View reviewed changes

Comment thread lib/rdoc/store.rb

Comment thread lib/rdoc/parser/ruby.rb

Conversation

st0012 commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Details

Uh oh!

matzbot commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

skatkov commented Apr 12, 2026

Uh oh!

st0012 commented Apr 12, 2026

Uh oh!

kou commented Apr 12, 2026

Uh oh!

st0012 commented Apr 12, 2026

Uh oh!

st0012 commented Apr 12, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

st0012 commented Mar 30, 2026 •

edited

Loading

matzbot commented Mar 30, 2026 •

edited

Loading