docscribe 1.4.1 → 1.4.2

data/lib/docscribe/plugin/base/collector_plugin.rb

@@ -40,9 +40,8 @@ module Docscribe
         # Each result is a Hash with:
         # - :anchor_node => Parser::AST::Node — node above which to insert doc
         # - :doc         => String — complete doc block including newlines
-        #
-        # @param [Object] _ast Param documentation.
-        # @param [Object] _buffer Param documentation.
+        # @param [Parser::AST::Node] _ast AST node to analyze
+        # @param [Parser::Source::Buffer] _buffer source buffer
         # @return [Array<Hash>]
         def collect(_ast, _buffer)
           []

data/lib/docscribe/plugin/base/tag_plugin.rb

@@ -27,7 +27,7 @@ module Docscribe
         # nothing to add for this particular method.
         #
         # @param [Docscribe::Plugin::Context] context method context snapshot
-        # @param [Object] _context Param documentation.
+        # @param [Docscribe::Plugin::Context] _context method context snapshot (unused in default)
         # @return [Array<Docscribe::Plugin::Tag>]
         def call(_context)
           []

data/lib/docscribe/plugin/registry.rb

@@ -45,16 +45,43 @@ module Docscribe
       # @raise [StandardError]
       # @return [void]
       def register(plugin, priority: 0)
-        prio =
-          begin
-            Integer(priority)
-          rescue StandardError
-            raise ArgumentError, "priority must be an Integer-like value, got: #{priority.inspect}"
-          end
+        prio = parse_priority(priority)
+        entry = create_entry(plugin, prio)
+        route_entry(entry, plugin)
+      end
+
+      # Parse and validate plugin priority.
+      #
+      # @note module_function: when included, also defines #parse_priority (instance visibility: private)
+      # @param [Object] priority
+      # @raise [ArgumentError]
+      # @raise [StandardError]
+      # @return [Integer]
+      def parse_priority(priority)
+        Integer(priority)
+      rescue StandardError
+        raise ArgumentError, "priority must be an Integer-like value, got: #{priority.inspect}"
+      end
 
+      # Create a new Entry with the next order number.
+      #
+      # @note module_function: when included, also defines #create_entry (instance visibility: private)
+      # @param [Object] plugin
+      # @param [Integer] priority
+      # @return [Entry]
+      def create_entry(plugin, priority)
         @order_seq += 1
-        entry = Entry.new(plugin: plugin, priority: prio, order: @order_seq)
+        Entry.new(plugin: plugin, priority: priority, order: @order_seq)
+      end
 
+      # Route entry to tag or collector list.
+      #
+      # @note module_function: when included, also defines #route_entry (instance visibility: private)
+      # @param [Entry] entry
+      # @param [Object] plugin
+      # @raise [ArgumentError]
+      # @return [void]
+      def route_entry(entry, plugin)
         if plugin.is_a?(Base::CollectorPlugin) || plugin.respond_to?(:collect)
           @collector_entries << entry
         elsif plugin.is_a?(Base::TagPlugin) || plugin.respond_to?(:call)

data/lib/docscribe/plugin.rb

@@ -48,25 +48,56 @@ module Docscribe
     # @raise [StandardError]
     # @return [Array<Hash>]
     def self.run_collector_plugins(ast, buffer)
-      Registry.collector_entries.flat_map do |entry|
-        plugin = entry.plugin
+      Registry.collector_entries.flat_map { |entry| process_single_plugin_result(entry, ast, buffer) }
+    end
 
-        Array(plugin.collect(ast, buffer)).map do |insertion|
-          unless insertion.is_a?(Hash)
-            warn "Docscribe: CollectorPlugin #{plugin.class} returned #{insertion.class}, expected Hash" if debug?
-            next nil
-          end
+    # Process a single collector plugin's result.
+    #
+    # Merges plugin metadata into each hash insertion and handles errors.
+    #
+    # @param [Entry] entry
+    # @param [Parser::AST::Node] ast
+    # @param [Parser::Source::Buffer] buffer
+    # @raise [StandardError]
+    # @return [Array<Hash>]
+    def self.process_single_plugin_result(entry, ast, buffer)
+      plugin = entry.plugin
+      results = Array(plugin.collect(ast, buffer))
+      process_plugin_insertions(results, entry, plugin)
+    rescue StandardError => e
+      warn "Docscribe: CollectorPlugin #{plugin.class} raised #{e.class}: #{e.message}" if debug?
+      []
+    end
 
-          insertion.merge(
-            __docscribe_priority: entry.priority,
-            __docscribe_plugin_class: plugin.class.name,
-            __docscribe_plugin_order: entry.order
-          )
-        end.compact
-      rescue StandardError => e
-        warn "Docscribe: CollectorPlugin #{plugin.class} raised #{e.class}: #{e.message}" if debug?
-        []
-      end
+    # Merge plugin metadata into collector results and filter invalid ones.
+    #
+    # @param [Array] results collector plugin results to process
+    # @param [Entry] entry registry entry with priority and order metadata
+    # @param [Base::CollectorPlugin] plugin the collector plugin instance
+    # @return [Array<Hash>]
+    def self.process_plugin_insertions(results, entry, plugin)
+      results.map do |insertion|
+        next nil unless valid_plugin_result?(insertion, plugin)
+
+        insertion.merge(
+          __docscribe_priority: entry.priority,
+          __docscribe_plugin_class: plugin.class.name,
+          __docscribe_plugin_order: entry.order
+        )
+      end.compact
+    end
+
+    # Validate a CollectorPlugin result is a Hash.
+    #
+    # @private
+    # @param [Object] insertion
+    # @param [Object] plugin
+    # @return [Boolean]
+    def self.valid_plugin_result?(insertion, plugin)
+      return true if insertion.is_a?(Hash)
+
+      warn "Docscribe: CollectorPlugin #{plugin.class} returned #{insertion.class}, expected Hash" if debug?
+      false
     end
 
     # @return [Boolean]

data/lib/docscribe/types/rbs/collection_loader.rb

@@ -1,4 +1,3 @@
-# lib/docscribe/types/rbs/collection_loader.rb
 # frozen_string_literal: true
 
 require 'pathname'

data/lib/docscribe/types/rbs/provider.rb

@@ -44,24 +44,12 @@ module Docscribe
         # @return [Docscribe::Types::MethodSignature, nil]
         def signature_for(container:, scope:, name:)
           load_env!
-
-          definition = definition_for(container: container, scope: scope)
-          method_def = definition.methods[name.to_sym]
-          return nil unless method_def
-
-          method_type = method_def.method_types.first
-          return nil unless method_type
-
-          func = method_type.type
-          build_signature(func)
+          lookup_signature(container, scope, name)
         rescue ::RBS::BaseError => e
-          warn_once("Docscribe: RBS error: #{e.class}: #{e.message}")
+          handle_rbs_error(e, 'RBS error')
           nil
         rescue StandardError => e
-          warn_once(
-            'Docscribe: RBS integration failed (falling back to inference): ' \
-            "#{e.class}: #{e.message}\nFeel free to open an issue on github."
-          )
+          handle_rbs_error(e, 'RBS integration failed (falling back to inference)')
           nil
         end
 
@@ -81,16 +69,50 @@ module Docscribe
         def load_env!
           return if @env && @builder
 
-          @env = build_env(@sig_dirs + @collection_dirs)
+          @env = try_with_fallback_build_env(
+            @sig_dirs + @collection_dirs,
+            @collection_dirs
+          )
+        end
+
+        # Look up a method signature from the loaded RBS definition builder.
+        #
+        # @private
+        # @param [String] container fully qualified class/module name
+        # @param [Symbol] scope :instance or :class
+        # @param [Symbol, String] name method name to look up
+        # @return [Docscribe::Types::MethodSignature, nil]
+        def lookup_signature(container, scope, name)
+          definition = definition_for(container: container, scope: scope)
+          method_def = definition.methods[name.to_sym]
+          return nil unless method_def
+
+          method_type = method_def.method_types.first
+          return nil unless method_type
+
+          build_signature(method_type.type)
+        end
+
+        # Try building an environment from combined dirs, falling back to
+        # user-only dirs on failure when collection dirs are present.
+        #
+        # @private
+        # @param [Array<String>] all_dirs combined sig and collection dirs
+        # @param [Array<String>] collection_dirs
+        # @raise [::RBS::BaseError]
+        # @raise [StandardError]
+        # @return [::RBS::Environment]
+        def try_with_fallback_build_env(all_dirs, collection_dirs)
+          build_env(all_dirs)
         rescue ::RBS::BaseError => e
-          raise unless @collection_dirs.any? && !@collection_dropped
+          raise unless collection_dirs.any? && !@collection_dropped
 
           @collection_dropped = true
           if ENV['DOCSCRIBE_RBS_DEBUG'] == '1'
             warn "Docscribe: RBS collection error (#{e.class}), dropping collection dirs. " \
                  'Set DOCSCRIBE_RBS_DEBUG=1 for details.'
           end
-          @env = build_env(@sig_dirs)
+          build_env(@sig_dirs)
         end
 
         # Build an RBS environment from the given directories.
@@ -121,7 +143,7 @@ module Docscribe
         # @return [Object]
         def definition_for(container:, scope:)
           type_name = parse_type_name(absolute_const(container))
-          scope == :class ? @builder.build_singleton(type_name) : @builder.build_instance(type_name)
+          scope == :class ? @builder&.build_singleton(type_name) : @builder&.build_instance(type_name)
         end
 
         # Parse a fully-qualified constant string into an RBS TypeName.
@@ -135,6 +157,7 @@ module Docscribe
         def parse_type_name(string)
           absolute = string.start_with?('::')
           *path, name = string.delete_prefix('::').split('::').map(&:to_sym)
+          name ||= :Object
           ::RBS::TypeName.new(
             name: name,
             namespace: ::RBS::Namespace.new(path: path, absolute: absolute)
@@ -172,21 +195,28 @@ module Docscribe
         # @param [::RBS::Types::Function] func
         # @return [Hash{String => String}]
         def build_param_types(func)
-          param_types = {}
+          param_types = {} #: Hash[String, String]
 
           add_positionals!(param_types, func.required_positionals)
           add_positionals!(param_types, func.optional_positionals)
           add_positionals!(param_types, func.trailing_positionals)
 
-          func.required_keywords.each do |kw, p|
-            param_types[kw.to_s] = format_type(p.type)
-          end
+          add_keywords!(param_types, func.required_keywords)
+          add_keywords!(param_types, func.optional_keywords)
+
+          param_types
+        end
 
-          func.optional_keywords.each do |kw, p|
+        # Add keyword parameters to the normalized parameter map.
+        #
+        # @private
+        # @param [Hash{String => String}] param_types
+        # @param [Hash{Symbol => Object}] keywords
+        # @return [void]
+        def add_keywords!(param_types, keywords)
+          keywords.each do |kw, p|
             param_types[kw.to_s] = format_type(p.type)
           end
-
-          param_types
         end
 
         # Add named positional parameters to the normalized parameter map.
@@ -246,6 +276,25 @@ module Docscribe
           )
         end
 
+        # Emit a formatted RBS error warning with context-specific messaging.
+        #
+        # @private
+        # @param [StandardError] e the raised exception
+        # @param [String] context human-readable context label
+        # @param [StandardError] error the raised exception
+        # @return [void]
+        def handle_rbs_error(error, context)
+          case error
+          when ::RBS::BaseError
+            warn_once("Docscribe: #{context}: #{error.class}: #{error.message}")
+          else
+            warn_once(
+              "Docscribe: #{context}: #{error.class}: #{error.message}\n" \
+              'Feel free to open an issue on github.'
+            )
+          end
+        end
+
         # Print one debug warning per provider instance when debugging is enabled.
         #
         # @private

data/lib/docscribe/types/rbs/type_formatter.rb

@@ -10,58 +10,97 @@ module Docscribe
       module TypeFormatter
         module_function
 
-        # Convert one RBS type object into a YARD-ish string.
+        # rubocop:disable Metrics/AbcSize, Layout/LineLength
+        # Return or memoize the dispatch hash mapping RBS type classes to formatter lambdas.
         #
-        # Supported categories include:
-        # - base types (`bool`, `nil`, `void`, `untyped`)
-        # - optional and union types
-        # - named types with optional generic arguments
-        # - literal types
-        # - Proc types
+        # @note module_function: when included, also defines #to_yard_formatters (instance visibility: private)
+        # @return [Hash{Class=>Proc}]
+        def to_yard_formatters
+          @to_yard_formatters ||= {
+            ::RBS::Types::Bases::Any => ->(_, **) { format_any },
+            ::RBS::Types::Bases::Bool => ->(_, **) { format_bool },
+            ::RBS::Types::Bases::Void => ->(_, **) { format_void },
+            ::RBS::Types::Bases::Nil => ->(_, **) { format_nil },
+            ::RBS::Types::Optional => ->(t, collapse_generics:) { format_optional(t, collapse_generics: collapse_generics) },
+            ::RBS::Types::Union => ->(t, collapse_generics:) { format_union(t, collapse_generics: collapse_generics) },
+            ::RBS::Types::Literal => ->(t, **) { format_literal(t.literal) },
+            ::RBS::Types::Proc => ->(_, **) { format_proc }
+          }.freeze
+        end
+        # rubocop:enable Metrics/AbcSize, Layout/LineLength
+
+        # Format RBS `any` type as the YARD-equivalent `Object`.
         #
-        # @note module_function: when included, also defines #to_yard (instance visibility: private)
-        # @param [Object] type RBS type object
-        # @param [Boolean] collapse_generics whether generic arguments should be omitted
+        # @note module_function: when included, also defines #format_any (instance visibility: private)
         # @return [String]
-        def to_yard(type, collapse_generics: false)
-          return 'Object' unless type
+        def format_any
+          'Object'
+        end
 
-          # RBS is loaded lazily by the provider; constants below exist only when rbs is available.
-          case type
-          when ::RBS::Types::Bases::Any
-            'Object'
-          when ::RBS::Types::Bases::Bool
-            'Boolean'
-          when ::RBS::Types::Bases::Void
-            'void'
-          when ::RBS::Types::Bases::Nil
-            'nil'
-          when ::RBS::Types::Optional
-            "#{to_yard(type.type, collapse_generics: collapse_generics)}?"
-          when ::RBS::Types::Union
-            format_union(type, collapse_generics: collapse_generics)
-          when ::RBS::Types::ClassInstance,
-            ::RBS::Types::ClassSingleton,
-            ::RBS::Types::Interface,
-            ::RBS::Types::Alias
-            format_named(type, collapse_generics: collapse_generics)
-          when ::RBS::Types::Literal
-            literal_to_yard(type.literal)
-          when ::RBS::Types::Proc
-            'Proc'
-          else
-            fallback_string(type)
+        # Format RBS `bool` type as the YARD `Boolean`.
+        #
+        # @note module_function: when included, also defines #format_bool (instance visibility: private)
+        # @return [String]
+        def format_bool
+          'Boolean'
+        end
+
+        # Format RBS `void` type as the YARD `void`.
+        #
+        # @note module_function: when included, also defines #format_void (instance visibility: private)
+        # @return [String]
+        def format_void
+          'void'
+        end
+
+        # Format RBS `nil` type as the YARD `nil`.
+        #
+        # @note module_function: when included, also defines #format_nil (instance visibility: private)
+        # @return [String]
+        def format_nil
+          'nil'
+        end
+
+        # Format an RBS Optional type as a YARD optional type with `?` suffix.
+        #
+        # @note module_function: when included, also defines #format_optional (instance visibility: private)
+        # @param [::RBS::Types::Optional] type the optional type to format
+        # @param [Boolean] collapse_generics whether to omit generic type arguments
+        # @return [String]
+        def format_optional(type, collapse_generics:)
+          "#{to_yard(type.type, collapse_generics: collapse_generics)}?"
+        end
+
+        # Map a Ruby literal value to its corresponding YARD type name.
+        #
+        # @note module_function: when included, also defines #format_literal (instance visibility: private)
+        # @param [Object] lit a Ruby literal value
+        # @return [String]
+        def format_literal(lit)
+          case lit
+          when Integer then 'Integer'
+          when Float   then 'Float'
+          when String  then 'String'
+          when Symbol  then 'Symbol'
+          when TrueClass, FalseClass then 'Boolean'
+          when NilClass then 'nil'
+          else 'Object'
           end
         end
 
-        # Format an RBS union type as a comma-separated YARD union.
+        # Format RBS Proc type as the YARD `Proc`.
         #
-        # Example:
-        # - `String | Integer | nil` => `"String, Integer, nil"`
+        # @note module_function: when included, also defines #format_proc (instance visibility: private)
+        # @return [String]
+        def format_proc
+          'Proc'
+        end
+
+        # Format an RBS Union type as a comma-separated list of YARD types.
         #
         # @note module_function: when included, also defines #format_union (instance visibility: private)
-        # @param [::RBS::Types::Union] type
-        # @param [Boolean] collapse_generics
+        # @param [::RBS::Types::Union] type the union type to format
+        # @param [Boolean] collapse_generics whether to omit generic type arguments
         # @return [String]
         def format_union(type, collapse_generics:)
           type.types.map { |t| to_yard(t, collapse_generics: collapse_generics) }
@@ -69,20 +108,15 @@ module Docscribe
               .join(', ')
         end
 
-        # Format a named RBS type, optionally preserving generic arguments.
-        #
-        # Examples:
-        # - `::String` => `"String"`
-        # - `::Hash[::Symbol, untyped]` => `"Hash<Symbol, Object>"`
-        # - with `collapse_generics: true` => `"Hash"`
+        # Format an RBS named type (class, interface, alias) with optional generic arguments.
         #
         # @note module_function: when included, also defines #format_named (instance visibility: private)
-        # @param [Object] type named RBS type
-        # @param [Boolean] collapse_generics
+        # @param [::RBS::Types::ClassInstance, ::RBS::Types::Interface, ::RBS::Types::Alias] type
+        # @param [Boolean] collapse_generics whether to omit generic type arguments
         # @return [String]
         def format_named(type, collapse_generics:)
           name = type.name.to_s.delete_prefix('::')
-          args = type.respond_to?(:args) ? type.args : []
+          args = type.respond_to?(:args) ? type.args : [] #: Array[untyped]
 
           if args && !args.empty?
             return name if collapse_generics
@@ -93,10 +127,10 @@ module Docscribe
           end
         end
 
-        # Map a literal Ruby value from an RBS literal type into a YARD-ish type name.
+        # Convert a Ruby literal value to its YARD type name string.
         #
         # @note module_function: when included, also defines #literal_to_yard (instance visibility: private)
-        # @param [Object] lit literal value
+        # @param [Object] lit a Ruby literal value
         # @return [String]
         def literal_to_yard(lit)
           case lit
@@ -110,15 +144,49 @@ module Docscribe
           end
         end
 
-        # Fallback string conversion for unsupported or unexpected RBS type objects.
+        # Dispatch an RBS type object to the appropriate YARD formatter.
         #
-        # Performs a few normalizations for nicer YARD output:
-        # - strips leading `::`
-        # - converts `bool` to `Boolean`
-        # - converts `untyped` to `Object`
+        # @note module_function: when included, also defines #to_yard (instance visibility: private)
+        # @param [::RBS::Type] type the RBS type object to convert
+        # @param [Boolean] collapse_generics whether to omit generic type arguments
+        # @return [String]
+        def to_yard(type, collapse_generics: false)
+          return 'Object' unless type
+
+          handler = to_yard_formatters.find { |klass, _| type.is_a?(klass) }
+          return handler.last.call(type, collapse_generics: collapse_generics) if handler
+
+          return format_named(type, collapse_generics: collapse_generics) if named_type?(type)
+
+          fallback_string(type)
+        end
+
+        # Check if the given type object is a named RBS type (class, singleton, interface, or alias).
+        #
+        # @note module_function: when included, also defines #named_type? (instance visibility: private)
+        # @param [::RBS::Type] type the RBS type object to check
+        # @return [Boolean]
+        def named_type?(type)
+          named_type_classes.any? { |klass| type.is_a?(klass) }
+        end
+
+        # Return or memoize the list of RBS type classes considered named types.
+        #
+        # @note module_function: when included, also defines #named_type_classes (instance visibility: private)
+        # @return [Array<Class>]
+        def named_type_classes
+          @named_type_classes ||= [
+            ::RBS::Types::ClassInstance,
+            ::RBS::Types::ClassSingleton,
+            ::RBS::Types::Interface,
+            ::RBS::Types::Alias
+          ].freeze
+        end
+
+        # Fallback conversion of an unrecognized RBS type to a cleaned string representation.
         #
         # @note module_function: when included, also defines #fallback_string (instance visibility: private)
-        # @param [Object] type
+        # @param [::RBS::Type] type the unrecognized RBS type object
         # @return [String]
         def fallback_string(type)
           type.to_s

data/lib/docscribe/types/sorbet/base_provider.rb

@@ -74,18 +74,25 @@ module Docscribe
             next unless decl.respond_to?(:members)
 
             container = normalize_container(decl.name.to_s)
+            decl.members.each { |member| process_method_member(container, member) }
+          end
+        end
 
-            decl.members.each do |member|
-              next unless method_definition_member?(member)
+        # Process a single method definition member into the index.
+        #
+        # @private
+        # @param [String] container normalized container name
+        # @param [Object] member
+        # @return [void]
+        def process_method_member(container, member)
+          return unless method_definition_member?(member)
 
-              scope = member.kind == :singleton ? :class : :instance
-              overload = member.overloads&.first
-              next unless overload
+          scope = member.kind == :singleton ? :class : :instance
+          overload = member.overloads&.first
+          return unless overload
 
-              func = overload.method_type.type
-              @index[[container, scope, member.name.to_s.to_sym]] = build_signature(func)
-            end
-          end
+          func = overload.method_type.type
+          @index[[container, scope, member.name.to_s.to_sym]] = build_signature(func)
         end
 
         # @private
@@ -116,18 +123,30 @@ module Docscribe
         # @param [::RBS::Types::Function] func
         # @return [Hash{String => String}]
         def build_param_types(func)
-          param_types = {}
+          param_types = {} #: Hash[String, String]
 
           add_positionals!(param_types, func.required_positionals)
           add_positionals!(param_types, func.optional_positionals)
           add_positionals!(param_types, func.trailing_positionals)
 
-          func.required_keywords.each { |kw, p| param_types[kw.to_s] = format_type(p.type) }
-          func.optional_keywords.each { |kw, p| param_types[kw.to_s] = format_type(p.type) }
+          add_keywords!(param_types, func.required_keywords)
+          add_keywords!(param_types, func.optional_keywords)
 
           param_types
         end
 
+        # Add keyword parameters to the normalized parameter map.
+        #
+        # @private
+        # @param [Hash{String => String}] param_types
+        # @param [Hash{Symbol => Object}] keywords
+        # @return [void]
+        def add_keywords!(param_types, keywords)
+          keywords.each do |kw, p|
+            param_types[kw.to_s] = format_type(p.type)
+          end
+        end
+
         # Add positional parameters with names to the normalized param map.
         #
         # @private

data/lib/docscribe/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Docscribe
-  VERSION = '1.4.1'
+  VERSION = '1.4.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docscribe
 version: !ruby/object:Gem::Version
-  version: 1.4.1
+  version: 1.4.2
 platform: ruby
 authors:
 - unurgunite
@@ -213,7 +213,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.12
+rubygems_version: 4.0.13
 specification_version: 4
 summary: Auto-generate inline YARD documentation for Ruby by analyzing code AST. Supports
   RBS and Sorbet type signatures.