Extract and display RBS type signatures in documentation

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`

Author: st0012

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
 
-  MARSHAL_VERSION = 3 # :nodoc:
+  MARSHAL_VERSION = 4 # :nodoc:
 
   ##
   # Don't rename \#initialize to \::new
@@ -60,6 +62,7 @@ def add_alias(an_alias, context = nil)
     method.visibility = self.visibility
     method.comment = an_alias.comment
     method.is_alias_for = self
+    method.type_signature = self.type_signature
     @aliases << method
     context.add_method method if context
     method
@@ -166,6 +169,7 @@ def marshal_dump
       @parent.class,
       @section.title,
       is_alias_for,
+      @type_signature,
     ]
   end
 
@@ -204,6 +208,7 @@ def marshal_load(array)
     @parent_title  = array[13]
     @section_title = array[14]
     @is_alias_for  = array[15]
+    @type_signature = array[16]
 
     array[8].each do |new_name, document|
       add_alias RDoc::Alias.new(nil, @name, new_name, RDoc::Comment.from_document(document), singleton: @singleton)

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
 
-  MARSHAL_VERSION = 3 # :nodoc:
+  MARSHAL_VERSION = 4 # :nodoc:
 
   ##
   # Is the attribute readable ('R'), writable ('W') or both ('RW')?
@@ -48,6 +50,7 @@ def add_alias(an_alias, context)
     new_attr.record_location an_alias.file
     new_attr.visibility = self.visibility
     new_attr.is_alias_for = self
+    new_attr.type_signature = self.type_signature
     @aliases << new_attr
     context.add_attribute new_attr
     new_attr
@@ -108,7 +111,8 @@ def marshal_dump
       @file.relative_name,
       @parent.full_name,
       @parent.class,
-      @section.title
+      @section.title,
+      @type_signature,
     ]
   end
 
@@ -140,6 +144,7 @@ def marshal_load(array)
     @parent_name   = array[8]
     @parent_class  = array[9]
     @section_title = array[10]
+    @type_signature = array[11]
 
     @file = RDoc::TopLevel.new array[7] if version > 1
 

lib/rdoc/code_object/method_attr.rb

@@ -58,6 +58,18 @@ class RDoc::MethodAttr < RDoc::CodeObject
 
   attr_accessor :call_seq
 
+  ##
+  # RBS type signature from inline annotations or loaded .rbs files
+
+  attr_accessor :type_signature
+
+  ##
+  # Returns the type signature split into individual lines.
+
+  def type_signature_lines
+    @type_signature&.split("\n")
+  end
+
   ##
   # The call_seq or the param_seq with method name, if there is no call_seq.
 
@@ -86,6 +98,7 @@ def initialize(text, name, singleton: false)
     @block_params = nil
     @call_seq     = nil
     @params       = nil
+    @type_signature = nil
   end
 
   ##

lib/rdoc/generator/aliki.rb

@@ -117,6 +117,21 @@ def write_search_index
     File.write search_index_path, "var search_data = #{JSON.generate(data)};"
   end
 
+  ##
+  # Returns the type signature of +method_attr+ as HTML with linked type names.
+  # Returns nil if no type signature is present.
+
+  def type_signature_html(method_attr, from_path)
+    lines = method_attr.type_signature_lines
+    return unless lines
+
+    RDoc::RbsHelper.signature_to_html(
+      lines,
+      lookup: @store.type_name_lookup,
+      from_path: from_path
+    )
+  end
+
   ##
   # Resolves a URL for use in templates. Absolute URLs are returned unchanged.
   # Relative URLs are prefixed with rel_prefix to ensure they resolve correctly from any page.

lib/rdoc/generator/template/aliki/class.rhtml

@@ -93,6 +93,9 @@
             <span class="method-name"><%= h attrib.name %></span>
             <span class="attribute-access-type">[<%= attrib.rw %>]</span>
           </a>
+          <%- if attrib.type_signature %>
+          <span class="method-type-signature"><code><%= type_signature_html(attrib, klass.path) %></code></span>
+          <%- end %>
         </div>
 
         <div class="method-description">
@@ -150,6 +153,10 @@
               </a>
             </div>
           <%- end %>
+
+          <%- if method.type_signature %>
+          <pre class="method-type-signature"><code><%= type_signature_html(method, klass.path) %></code></pre>
+          <%- end %>
         </div>
 
         <%- if method.token_stream %>

lib/rdoc/generator/template/aliki/css/rdoc.css

@@ -1075,6 +1075,20 @@ main h6 a:hover {
   font-style: italic;
 }
 
+/* RBS Type Signature Links — linked types get subtle underline */
+a.rbs-type {
+  color: inherit;
+  text-decoration: underline;
+  text-decoration-color: var(--color-border-default);
+  text-underline-offset: 0.2em;
+  transition: text-decoration-color var(--transition-fast), color var(--transition-fast);
+}
+
+a.rbs-type:hover {
+  color: var(--color-link-hover);
+  text-decoration-color: var(--color-link-hover);
+}
+
 /* Emphasis */
 em {
   text-decoration-color: var(--color-emphasis-decoration);
@@ -1335,6 +1349,49 @@ main .method-heading .method-args {
   font-weight: var(--font-weight-normal);
 }
 
+/* Type signatures — overloads stack as a code block under the method name */
+pre.method-type-signature {
+  position: relative;
+  margin: var(--space-2) 0 0;
+  padding: var(--space-2) 0 0;
+  background: transparent;
+  border: none;
+  border-radius: 0;
+  overflow: visible;
+  font-family: var(--font-code);
+  font-size: var(--font-size-sm);
+  color: var(--color-text-tertiary);
+  line-height: var(--line-height-tight);
+  white-space: pre-wrap;
+  overflow-wrap: break-word;
+}
+
+pre.method-type-signature::before {
+  content: '';
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  border-top: 1px dotted var(--color-border-default);
+}
+
+pre.method-type-signature code {
+  font-family: inherit;
+  font-size: inherit;
+  color: inherit;
+  background: transparent;
+  padding: 0;
+}
+
+/* Attribute type sigs render inline after the [RW] badge */
+main .method-heading > .method-type-signature {
+  display: inline;
+  margin-left: var(--space-2);
+  font-family: var(--font-code);
+  font-size: var(--font-size-sm);
+  color: var(--color-text-secondary);
+}
+
 main .method-controls {
   position: absolute;
   top: var(--space-3);
@@ -1444,6 +1501,10 @@ main .attribute-access-type {
     font-size: var(--font-size-base);
   }
 
+  pre.method-type-signature {
+    font-size: var(--font-size-xs);
+  }
+
   main .method-header {
     padding: var(--space-2);
     padding-right: var(--space-2);

lib/rdoc/generator/template/aliki/js/aliki.js

@@ -435,8 +435,8 @@ function wrapCodeBlocksWithCopyButton() {
   //   not directly in rhtml templates
   // - Modifying the formatter would require extending RDoc's core internals
 
-  // Find all pre elements that are not already wrapped
-  const preElements = document.querySelectorAll('main pre:not(.code-block-wrapper pre)');
+  // Target code examples and source code; skip type signature blocks
+  const preElements = document.querySelectorAll('main pre:not(.method-type-signature)');
 
   preElements.forEach((pre) => {
     // Skip if already wrapped

lib/rdoc/parser/prism_ruby.rb

@@ -2,6 +2,7 @@
 
 require 'prism'
 require_relative 'ripper_state_lex'
+require_relative '../rbs_helper'
 
 # Unlike lib/rdoc/parser/ripper_ruby.rb, this file is not based on rtags and does not contain code from
 #   rtags.rb -
@@ -133,6 +134,9 @@ class RDoc::Parser::PrismRuby < RDoc::Parser
 
   parse_files_matching(/\.rbw?$/) unless ENV['RDOC_USE_RIPPER_PARSER']
 
+  # Matches an RBS inline type annotation line: #: followed by whitespace
+  RBS_SIG_LINE = /\A#:\s/ # :nodoc:
+
   attr_accessor :visibility
   attr_reader :container, :singleton, :in_proc_block
 
@@ -461,10 +465,14 @@ def skip_comments_until(line_no_until)
   def consecutive_comment(line_no)
     return unless @unprocessed_comments.first&.first == line_no
     _line_no, start_line, text = @unprocessed_comments.shift
-    parse_comment_text_to_directives(text, start_line)
+    type_signature = extract_type_signature!(text, start_line)
+    result = parse_comment_text_to_directives(text, start_line)
+    return unless result
+    comment, directives = result
+    [comment, directives, type_signature]
   end
 
-  # Parses comment text and retuns a pair of RDoc::Comment and directives
+  # Parses comment text and returns a pair of RDoc::Comment and directives
 
   def parse_comment_text_to_directives(comment_text, start_line) # :nodoc:
     comment_text, directives = @preprocess.parse_comment(comment_text, start_line, :ruby)
@@ -594,14 +602,15 @@ def add_alias_method(old_name, new_name, line_no)
   # Handles `attr :a, :b`, `attr_reader :a, :b`, `attr_writer :a, :b` and `attr_accessor :a, :b`
 
   def add_attributes(names, rw, line_no)
-    comment, directives = consecutive_comment(line_no)
+    comment, directives, type_signature = consecutive_comment(line_no)
     handle_code_object_directives(@container, directives) if directives
     return unless @container.document_children
 
     names.each do |symbol|
       a = RDoc::Attr.new(nil, symbol.to_s, rw, comment, singleton: @singleton)
       a.store = @store
       a.line = line_no
+      a.type_signature = type_signature
       record_location(a)
       handle_modifier_directive(a, line_no)
       @container.add_attribute(a) if should_document?(a)
@@ -640,7 +649,7 @@ def add_extends(names, line_no) # :nodoc:
 
   def add_method(method_name, receiver_name:, receiver_fallback_type:, visibility:, singleton:, params:, calls_super:, block_params:, tokens:, start_line:, args_end_line:, end_line:)
     receiver = receiver_name ? find_or_create_module_path(receiver_name, receiver_fallback_type) : @container
-    comment, directives = consecutive_comment(start_line)
+    comment, directives, type_signature = consecutive_comment(start_line)
     handle_code_object_directives(@container, directives) if directives
 
     internal_add_method(
@@ -655,11 +664,12 @@ def add_method(method_name, receiver_name:, receiver_fallback_type:, visibility:
       params: params,
       calls_super: calls_super,
       block_params: block_params,
-      tokens: tokens
+      tokens: tokens,
+      type_signature: type_signature
     )
   end
 
-  private def internal_add_method(method_name, container, comment:, dont_rename_initialize: false, directives:, modifier_comment_lines: nil, line_no:, visibility:, singleton:, params:, calls_super:, block_params:, tokens:) # :nodoc:
+  private def internal_add_method(method_name, container, comment:, dont_rename_initialize: false, directives:, modifier_comment_lines: nil, line_no:, visibility:, singleton:, params:, calls_super:, block_params:, tokens:, type_signature: nil) # :nodoc:
     meth = RDoc::AnyMethod.new(nil, method_name, singleton: singleton)
     meth.comment = comment
     handle_code_object_directives(meth, directives) if directives
@@ -680,6 +690,7 @@ def add_method(method_name, receiver_name:, receiver_fallback_type:, visibility:
     meth.params ||= params || '()'
     meth.calls_super = calls_super
     meth.block_params ||= block_params if block_params
+    meth.type_signature = type_signature
     record_location(meth)
     meth.start_collecting_tokens(:ruby)
     tokens.each do |token|
@@ -836,6 +847,36 @@ def add_module_or_class(module_name, start_line, end_line, is_class: false, supe
     mod
   end
 
+  private
+
+  # Extracts RBS type signature lines (#: ...) from raw comment text.
+  # Mutates the input text to remove the extracted lines.
+  # Returns the type signature string, or nil if none found.
+
+  def extract_type_signature!(text, start_line)
+    return nil unless text.include?('#:')
+
+    lines = text.lines
+    sig_lines, doc_lines = lines.partition { |l| l.match?(RBS_SIG_LINE) }
+    return nil if sig_lines.empty?
+
+    first_sig_line = start_line + lines.index(sig_lines.first)
+    text.replace(doc_lines.join)
+    type_sig = sig_lines.map { |l| l.sub(RBS_SIG_LINE, '') }.join.chomp
+    return nil if type_sig.strip.empty?
+
+    warn_invalid_type_signature(type_sig, first_sig_line)
+    type_sig
+  end
+
+  def warn_invalid_type_signature(sig, line_no)
+    sig.each_line(chomp: true).with_index do |line, i|
+      next if RDoc::RbsHelper.valid_method_type?(line)
+      next if RDoc::RbsHelper.valid_type?(line)
+      @options.warn "#{@top_level.relative_name}:#{line_no + i}: invalid RBS type signature: #{line.inspect}"
+    end
+  end
+
   class RDocVisitor < Prism::Visitor # :nodoc:
     def initialize(scanner, top_level, store)
       @scanner = scanner