Add support for Ruby Signature Files (.rbs) (#1673)

Add support for Ruby Signature Files (.rbs) including fully docstring
support.

Author: lsegal

CHANGELOG.md

@@ -1,5 +1,6 @@
 # main
 
+- Add support for Ruby .rbs files (docstrings included)
 - Add support for `#-` as a comment-block separator. See Getting Started Guide.
 - Fix false self-referential mixin when bare name matches ancestor namespace (#1672)
 - Fix bracket/brace map corruption from Ruby 3.0+ pattern matching deconstruction (#1671)

docs/WhatsNew.md

@@ -2,7 +2,11 @@
 
 # What's New in 0.9.x?
 
-## `#-` comment block separators
+## Support for Ruby Signature Files (.rbs) (0.9.40)
+
+YARD now supports parsing Ruby signature files (.rbs) with full docstring support. This means you can write your documentation in `.rbs` files and have it show up in generated documentation, and use `.rbs` files alongside `.rb` sources to supplement type and API information.
+
+## `#-` comment block separators (0.9.40)
 
 YARD now recognizes a trailing `#-` line as a separator between comment
 blocks. This is useful when you want to keep a file header comment at the top
@@ -22,7 +26,7 @@ In the example above, the file header stays disconnected from `Client`.
 Note that `# -` does **not** act as a separator; only an attached `#-`
 line has this behavior.
 
-## Ruby 4.x support
+## Ruby 4.x support (0.9.39)
 
 Added support for Ruby 4.x along with new syntaxes.
 

lib/yard/autoload.rb

@@ -69,6 +69,16 @@ module Common
       autoload :MethodHandler,            __p('handlers/common/method_handler')
     end
 
+    # RBS type signature handlers
+    module RBS
+      autoload :Base,               __p('handlers/rbs/base')
+      autoload :AttributeHandler,   __p('handlers/rbs/attribute_handler')
+      autoload :ConstantHandler,    __p('handlers/rbs/constant_handler')
+      autoload :MethodHandler,      __p('handlers/rbs/method_handler')
+      autoload :MixinHandler,       __p('handlers/rbs/mixin_handler')
+      autoload :NamespaceHandler,   __p('handlers/rbs/namespace_handler')
+    end
+
     # CRuby Handlers
     # @since 0.8.0
     module C
@@ -183,6 +193,12 @@ module Legacy # Handles Ruby parsing in Ruby 1.8.
       autoload :TokenResolver,     __p('parser/ruby/token_resolver')
     end
 
+    # RBS type signature parser
+    module RBS
+      autoload :RbsParser, __p('parser/rbs/rbs_parser')
+      autoload :Statement, __p('parser/rbs/statement')
+    end
+
     autoload :Base,                __p('parser/base')
     autoload :ParserSyntaxError,   __p('parser/source_parser')
     autoload :SourceParser,        __p('parser/source_parser')

lib/yard/handlers/processor.rb

@@ -35,6 +35,7 @@ def namespace_for_handler; @@parser_type_extensions ||= {} end
       register_handler_namespace :ruby, Ruby
       register_handler_namespace :ruby18, Ruby::Legacy
       register_handler_namespace :c, C
+      register_handler_namespace :rbs, RBS
 
       # @return [String] the filename
       attr_accessor :file

lib/yard/handlers/rbs/attribute_handler.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+# Handles RBS attr_reader, attr_writer, and attr_accessor declarations.
+#
+# Registers one or two {YARD::CodeObjects::MethodObject} instances (reader
+# and/or writer) with @return / @param tags derived from the RBS type.
+class YARD::Handlers::RBS::AttributeHandler < YARD::Handlers::RBS::Base
+  handles :attr_reader, :attr_writer, :attr_accessor
+
+  process do
+    attr_name  = statement.name
+    rbs_type   = statement.attr_rbs_type
+    yard_types = rbs_type ? YARD::Handlers::RBS::MethodHandler.rbs_type_to_yard_types(rbs_type) : nil
+    mscope     = statement.visibility == :class ? :class : :instance
+
+    case statement.type
+    when :attr_reader
+      register_reader(attr_name, yard_types, mscope)
+    when :attr_writer
+      register_writer(attr_name, yard_types, mscope)
+    when :attr_accessor
+      register_reader(attr_name, yard_types, mscope)
+      register_writer(attr_name, yard_types, mscope)
+    end
+  end
+
+  private
+
+  def register_reader(name, types, scope)
+    obj = register MethodObject.new(namespace, name, scope)
+    if types && !obj.has_tag?(:return)
+      obj.add_tag YARD::Tags::Tag.new(:return, '', types)
+    end
+    obj
+  end
+
+  def register_writer(name, types, scope)
+    obj = register MethodObject.new(namespace, "#{name}=", scope)
+    if types && !obj.has_tag?(:param)
+      obj.add_tag YARD::Tags::Tag.new(:param, '', types, "value")
+    end
+    obj
+  end
+end

lib/yard/handlers/rbs/base.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+module YARD
+  module Handlers
+    # Handlers for RBS (Ruby type signature) files.
+    module RBS
+      # Base class for all RBS handlers.
+      # Handlers match on the {Parser::RBS::Statement#type} symbol of the
+      # current statement and process it to create or annotate code objects.
+      class Base < Handlers::Base
+        # @return [Boolean] whether this handler matches the given statement
+        def self.handles?(statement, _processor)
+          handlers.any? do |matcher|
+            case matcher
+            when Symbol
+              statement.type == matcher
+            when String
+              statement.type.to_s == matcher
+            when Regexp
+              (statement.source || '') =~ matcher
+            else
+              false
+            end
+          end
+        end
+
+        # Recurse into the body of a namespace statement.
+        # @param opts [Hash] state overrides
+        # @see #push_state
+        def parse_block(opts = {})
+          return if statement.block.nil? || statement.block.empty?
+          push_state(opts) do
+            parser.process(statement.block)
+          end
+        end
+      end
+    end
+  end
+end

lib/yard/handlers/rbs/constant_handler.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# Handles RBS constant declarations: `Name: Type`
+class YARD::Handlers::RBS::ConstantHandler < YARD::Handlers::RBS::Base
+  handles :constant
+
+  process do
+    obj = register ConstantObject.new(namespace, statement.name)
+    if statement.attr_rbs_type && !obj.has_tag?(:return)
+      obj.add_tag YARD::Tags::Tag.new(:return, '', rbs_types(statement.attr_rbs_type))
+    end
+  end
+
+  private
+
+  def rbs_types(type_str)
+    YARD::Handlers::RBS::MethodHandler.rbs_type_to_yard_types(type_str)
+  end
+end