Extract and display RBS type signatures in documentation

Add `type_signature` accessor to `MethodAttr`. During Prism parsing,
extract `#:` annotation lines from comment blocks and store them on
methods and attributes. Bump Marshal to v4 for RI serialization.

Render type signatures in the aliki theme with server-side type name
linking via `RbsSupport.signature_to_html`. Uses the RBS parser to
extract type name locations precisely for linking to documentation
pages. Validate annotations through `RBS::Parser` — invalid sigs
emit a warning but are still displayed.

Load additional signatures from `sig/` directories and RBS core
types via `RBS::EnvironmentLoader`. Display type signatures in `ri`
terminal output.

Author: st0012

lib/rdoc/code_object/any_method.rb

@@ -14,7 +14,7 @@ class RDoc::AnyMethod < RDoc::MethodAttr
   #   RDoc 4.1
   #   Added is_alias_for
 
-  MARSHAL_VERSION = 3 # :nodoc:
+  MARSHAL_VERSION = 4 # :nodoc:
 
   ##
   # Don't rename \#initialize to \::new
@@ -166,6 +166,7 @@ def marshal_dump
       @parent.class,
       @section.title,
       is_alias_for,
+      @type_signature,
     ]
   end
 
@@ -204,6 +205,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

@@ -11,7 +11,7 @@ class RDoc::Attr < RDoc::MethodAttr
   #    Added parent name and class
   #    Added section title
 
-  MARSHAL_VERSION = 3 # :nodoc:
+  MARSHAL_VERSION = 4 # :nodoc:
 
   ##
   # Is the attribute readable ('R'), writable ('W') or both ('RW')?
@@ -108,7 +108,8 @@ def marshal_dump
       @file.relative_name,
       @parent.full_name,
       @parent.class,
-      @section.title
+      @section.title,
+      @type_signature,
     ]
   end
 
@@ -140,6 +141,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,11 @@ class RDoc::MethodAttr < RDoc::CodeObject
 
   attr_accessor :call_seq
 
+  ##
+  # RBS type signature from inline #: annotations
+
+  attr_accessor :type_signature
+
   ##
   # The call_seq or the param_seq with method name, if there is no call_seq.
 
@@ -86,6 +91,7 @@ def initialize(text, name, singleton: false)
     @block_params = nil
     @call_seq     = nil
     @params       = nil
+    @type_signature = nil
   end
 
   ##

lib/rdoc/generator/markup.rb

@@ -141,6 +141,26 @@ def markup_code
     src
   end
 
+  ##
+  # Returns the type signature as HTML with type names linked to their
+  # documentation pages. Delegates to RDoc::RbsSupport for RBS-aware parsing.
+  #
+  # Falls back to escaped HTML without links when the store or parent
+  # path is unavailable (e.g. in ri mode).
+
+  def type_signature_html
+    return unless @type_signature
+
+    store = @store || parent&.store
+    from_path = parent&.path
+    lookup = store&.type_name_lookup
+
+    RDoc::RbsSupport.signature_to_html(@type_signature, lookup: lookup) do |name, target_path|
+      href = RDoc::Markup::ToHtml.gen_relative_url(from_path, target_path)
+      "<a href=\"#{href}\" class=\"rbs-type\">#{ERB::Util.html_escape(name)}</a>"
+    end
+  end
+
 end
 
 class RDoc::ClassModule

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

@@ -91,8 +91,9 @@
         <div class="method-heading attribute-method-heading">
           <a href="#<%= attrib.aref %>" title="Link to this attribute">
             <span class="method-name"><%= h attrib.name %></span>
-            <span class="attribute-access-type">[<%= attrib.rw %>]</span>
-          </a>
+            <span class="attribute-access-type">[<%= attrib.rw %>]</span></a><%- if attrib.type_signature %>
+          <span class="method-type-signature"><code><%= attrib.type_signature_html %></code></span>
+          <%- end %>
         </div>
 
         <div class="method-description">
@@ -150,6 +151,10 @@
               </a>
             </div>
           <%- end %>
+
+          <%- if method.type_signature %>
+          <pre class="method-type-signature"><code><%= method.type_signature_html %></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);
@@ -1334,6 +1348,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);
@@ -1440,6 +1497,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);
   }

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

@@ -461,7 +461,37 @@ 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)
+    result = parse_comment_text_to_directives(text, start_line)
+    return unless result
+    comment, directives = result
+    [comment, directives, type_signature]
+  end
+
+  # 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.
+  private def extract_type_signature!(text)
+    return nil unless text.include?('#:')
+
+    lines = text.lines
+    sig_lines, doc_lines = lines.partition { |l| l.match?(/\A#:\s/) }
+    return nil if sig_lines.empty?
+
+    text.replace(doc_lines.join)
+    type_sig = sig_lines.map { |l| l.sub(/\A#:\s?/, '').chomp }.join("\n")
+    validate_type_signature(type_sig)
+    type_sig
+  end
+
+  private def validate_type_signature(sig)
+    sig.split("\n").each do |line|
+      method_error = RDoc::RbsSupport.validate_method_type(line)
+      next unless method_error
+      type_error = RDoc::RbsSupport.validate_type(line)
+      next unless type_error
+      @options.warn "Invalid RBS type signature: #{line.inspect}"
+    end
   end
 
   # Parses comment text and retuns a pair of RDoc::Comment and directives
@@ -594,14 +624,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 +671,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 +686,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 +712,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|