docscribe 1.4.2 → 1.5.0

data/lib/docscribe/config/loader.rb

@@ -10,7 +10,7 @@ module Docscribe
     # - `docscribe.yml` in the current directory, if present
     # - otherwise defaults only
     #
-    # @param [String, nil] path optional config path
+    # @param [String?] path optional config path
     # @return [Docscribe::Config]
     def self.load(path = nil)
       raw = {} #: Hash[String, untyped]
@@ -28,11 +28,13 @@ module Docscribe
     # and calling {safe_load_compat}.
     #
     # @param [String] path file path
-    # @return [Hash]
+    # @return [Hash<String, Object>]
     def self.safe_load_file_compat(path)
-      if YAML.respond_to?(:safe_load_file)
-        YAML.safe_load_file(path,
-                            permitted_classes: [], permitted_symbols: [],
+      if YAML.respond_to?(:safe_load_file) # steep:ignore
+        pclasses = [] #: Array[String]
+        psymbols = [] #: Array[Symbol]
+        YAML.safe_load_file(path, # steep:ignore
+                            permitted_classes: pclasses, permitted_symbols: psymbols,
                             aliases: true) || {} #: Hash[String, untyped]
       else
         yaml = File.open(path, 'r:bom|utf-8', &:read)
@@ -43,20 +45,22 @@ module Docscribe
     # Safely load YAML from a string across Psych API versions.
     #
     # @param [String] yaml YAML document
-    # @param [String, nil] filename optional filename for diagnostics
+    # @param [String?] filename optional filename for diagnostics
     # @raise [ArgumentError]
-    # @return [Hash]
+    # @return [Hash<String, Object>] if ArgumentError
+    # @return [Object] if ArgumentError
     def self.safe_load_compat(yaml, filename: nil)
-      Psych.safe_load(
+      pclasses = [] #: Array[String]
+      psymbols = [] #: Array[Symbol]
+      Psych.safe_load( # steep:ignore
         yaml,
-        permitted_classes: [],
-        permitted_symbols: [],
+        permitted_classes: pclasses, permitted_symbols: psymbols,
         aliases: true,
         filename: filename
       ) #: Hash[String, untyped]
     rescue ArgumentError
       # Older Psych signature uses positional args
-      Psych.safe_load(yaml, [], [], true, filename)
+      Psych.safe_load(yaml, [], [], true, filename) # steep:ignore
     end
   end
 end

data/lib/docscribe/config/plugin.rb

@@ -15,7 +15,7 @@ module Docscribe
     # @raise [LoadError]
     # @return [void]
     def load_plugins!
-      paths = Array(raw.dig('plugins', 'require')).compact
+      paths = Array(raw.dig('plugins', 'require')).compact #: Array[String]
       return if paths.empty?
 
       require 'docscribe/plugin'

data/lib/docscribe/config/rbs.rb

@@ -8,7 +8,6 @@ module Docscribe
     # If RBS cannot be loaded, this returns nil and Docscribe falls back to
     # inference.
     #
-    # @raise [LoadError]
     # @return [Docscribe::Types::RBS::Provider, nil]
     def rbs_provider
       return nil unless rbs_enabled?
@@ -24,14 +23,25 @@ module Docscribe
       fetch_bool(%w[rbs enabled], false)
     end
 
-    # @raise [LoadError]
-    # @return [Object]
+    # Core rbs provider
+    #
+    # @return [Docscribe::Types::RBS::Provider, nil]
     def core_rbs_provider
       return nil unless ruby_supports_rbs?
 
       @core_rbs_provider ||= build_core_rbs_provider
     end
 
+    # Whether to warn when rbs_collection.lock.yaml exists but --rbs-collection
+    # was not passed.
+    #
+    # Set `rbs.warn_missing_collection: false` in `docscribe.yml` to suppress.
+    #
+    # @return [Boolean]
+    def rbs_warn_missing_collection?
+      fetch_bool(%w[rbs warn_missing_collection], true)
+    end
+
     private
 
     # Check whether the current Ruby version supports RBS (requires 3.0+).
@@ -48,23 +58,31 @@ module Docscribe
       false
     end
 
+    # Build rbs provider
+    #
     # @private
     # @raise [LoadError]
-    # @return [Docscribe::Types::RBS::Provider, nil]
+    # @return [Docscribe::Types::RBS::Provider, nil] if LoadError
+    # @return [nil] if LoadError
     def build_rbs_provider
       require 'docscribe/types/rbs/provider'
       Docscribe::Types::RBS::Provider.new(
         sig_dirs: rbs_sig_dirs,
         collection_dirs: rbs_collection_dirs,
-        collapse_generics: rbs_collapse_generics?
+        collapse_generics: rbs_collapse_generics?,
+        collapse_object_generics: rbs_collapse_object_generics?
       )
     rescue LoadError
+      warn 'Docscribe: --rbs requires the `rbs` gem. Add `gem "rbs"` to your Gemfile and run `bundle install`.'
       nil
     end
 
+    # Build core rbs provider
+    #
     # @private
     # @raise [LoadError]
-    # @return [Docscribe::Types::RBS::Provider, nil]
+    # @return [Docscribe::Types::RBS::Provider, nil] if LoadError
+    # @return [nil] if LoadError
     def build_core_rbs_provider
       require 'docscribe/types/rbs/provider'
       Docscribe::Types::RBS::Provider.new(
@@ -80,7 +98,7 @@ module Docscribe
     # @private
     # @return [Array<String>]
     def rbs_sig_dirs
-      Array(raw.dig('rbs', 'sig_dirs') || DEFAULT.dig('rbs', 'sig_dirs')).map(&:to_s)
+      Array(raw.dig('rbs', 'sig_dirs') || DEFAULT.dig('rbs', 'sig_dirs')).map(&:to_s) # steep:ignore
     end
 
     # RBS collection directories (auto-discovered from rbs_collection.lock.yaml).
@@ -92,7 +110,7 @@ module Docscribe
     # @private
     # @return [Array<String>]
     def rbs_collection_dirs
-      Array(raw.dig('rbs', 'collection_dirs')).map(&:to_s)
+      Array(raw.dig('rbs', 'collection_dirs')).map(&:to_s) # steep:ignore
     end
 
     # Whether generic RBS types should be collapsed to simpler container names.
@@ -102,9 +120,23 @@ module Docscribe
     # - `Array<Integer>`       => `Array`
     #
     # @private
-    # @return [Object]
+    # @return [Boolean]
     def rbs_collapse_generics?
       fetch_bool(%w[rbs collapse_generics], false)
     end
+
+    # Whether to collapse generic types when all inner types are Object.
+    #
+    # Unlike `collapse_generics` (which drops all generic info), this only
+    # collapses when the type arguments provide no useful information:
+    # - `Hash<Symbol, Object>` => stays as is (Symbol is useful)
+    # - `Hash<Object, Object>` => `Hash`
+    # - `Array<Object>`        => `Array`
+    #
+    # @private
+    # @return [Boolean]
+    def rbs_collapse_object_generics?
+      fetch_bool(%w[rbs collapse_object_generics], false)
+    end
   end
 end

data/lib/docscribe/config/sorbet.rb

@@ -14,7 +14,6 @@ module Docscribe
     #
     # @param [String] source Ruby source being rewritten
     # @param [String] file source name for diagnostics
-    # @raise [LoadError]
     # @return [Docscribe::Types::ProviderChain, nil]
     def signature_provider_for(source:, file:)
       providers = [] #: Array[untyped]
@@ -25,10 +24,9 @@ module Docscribe
 
     # Append Sorbet-based providers to the list.
     #
-    # @private
-    # @param [Array] providers
-    # @param [String] source
-    # @param [String] file
+    # @param [Array<Object>] providers provider list to populate
+    # @param [String] source Ruby source being rewritten
+    # @param [String] file source name for diagnostics
     # @return [void]
     def append_sorbet_providers(providers, source:, file:)
       return unless sorbet_enabled?
@@ -39,11 +37,11 @@ module Docscribe
 
     # Build a Sorbet source provider (inline sigs).
     #
-    # @private
-    # @param [String] source
-    # @param [String] file
+    # @param [String] source Ruby source being rewritten
+    # @param [String] file source name for diagnostics
     # @raise [LoadError]
-    # @return [Docscribe::Types::Sorbet::SourceProvider, nil]
+    # @return [Docscribe::Types::Sorbet::SourceProvider, nil] if LoadError
+    # @return [nil] if LoadError
     def sorbet_source_provider(source, file)
       require 'docscribe/types/sorbet/source_provider'
       Docscribe::Types::Sorbet::SourceProvider.new(
@@ -57,8 +55,7 @@ module Docscribe
 
     # Build the provider chain from a non-empty list, or return nil.
     #
-    # @private
-    # @param [Array] providers
+    # @param [Array<Object>] providers provider list to chain
     # @return [Docscribe::Types::ProviderChain, nil]
     def build_provider_chain(providers)
       providers = providers.compact
@@ -97,7 +94,7 @@ module Docscribe
     #
     # @return [Array<String>]
     def sorbet_rbi_dirs
-      Array(raw.dig('sorbet', 'rbi_dirs') || DEFAULT.dig('sorbet', 'rbi_dirs')).map(&:to_s)
+      Array(raw.dig('sorbet', 'rbi_dirs') || DEFAULT.dig('sorbet', 'rbi_dirs')).map(&:to_s) # steep:ignore
     end
 
     # Whether generic Sorbet/RBI container types should be simplified.

data/lib/docscribe/config/sorting.rb

@@ -17,7 +17,7 @@ module Docscribe
     # @return [Array<String>]
     def tag_order
       Array(raw.dig('doc', 'tag_order') || DEFAULT.dig('doc', 'tag_order')).map do |t|
-        t.to_s.sub(/\A@/, '')
+        t.to_s.sub(/\A@/, '') # steep:ignore
       end
     end
   end

data/lib/docscribe/config/template.rb

@@ -7,7 +7,6 @@ module Docscribe
     #
     # The template documents the most common CLI workflows and all supported
     # configuration sections with comments.
-    # @see Docscribe::Config::DEFAULT
     #
     # @return [String]
     def self.default_yaml
@@ -21,6 +20,7 @@ module Docscribe
         #   bundle exec docscribe lib          # check what would change
         #   bundle exec docscribe -a lib       # apply safe updates
         #   bundle exec docscribe -A lib       # rebuild all doc blocks
+        #   bundle exec docscribe -AkB lib     # rebuild, keep descriptions, no boilerplate
 
         emit:
           # What to include in generated documentation
@@ -89,7 +89,9 @@ module Docscribe
           sig_dirs: ["sig"]
           collection_dirs: []                 # auto-discovered from --rbs-collection
           collapse_generics: false            # Hash<Symbol, String> => Hash
+          collapse_object_generics: false     # Hash<Object, Object> => Hash (keep if inner types are useful)
           collection: false                   # auto-discover from rbs_collection.lock.yaml
+          warn_missing_collection: true       # warn if rbs_collection.lock.yaml exists without --rbs-collection
 
         sorbet:
           # Use Sorbet inline sigs and RBI files for better types
@@ -97,6 +99,12 @@ module Docscribe
           rbi_dirs: ["sorbet/rbi", "rbi"]
           collapse_generics: false
 
+        # Preserve existing @param/@return descriptions in aggressive mode
+        keep_descriptions: false
+
+        # Skip @param for anonymous block arguments (&) (Ruby 3.2+)
+        skip_anonymous_block_params: false
+
         plugins:
           # Load custom plugins
           # Example:

data/lib/docscribe/config/utils.rb

@@ -46,7 +46,7 @@ module Docscribe
     # Convert an internal scope symbol into the config key used under `methods`.
     #
     # @private
-    # @param [Symbol] scope
+    # @param [Symbol] scope :instance or :class
     # @return [String]
     def scope_to_key(scope)
       scope == :class ? 'class' : 'instance'
@@ -55,8 +55,8 @@ module Docscribe
     # Check whether any pattern matches the given text.
     #
     # @private
-    # @param [Array<String>] patterns
-    # @param [String] text
+    # @param [Array<String>] patterns filter patterns to match
+    # @param [String] text text to test against patterns
     # @return [Boolean]
     def matches_any?(patterns, text)
       patterns.any? { |pat| match_pattern?(pat, text) }
@@ -69,12 +69,14 @@ module Docscribe
     # - shell-style glob patterns (with `/` translated to `#` since method IDs use `#`)
     #
     # @private
-    # @param [String] pattern
-    # @param [String] text
+    # @param [String] pattern filter pattern to match
+    # @param [String] text method ID to test
     # @return [Boolean]
     def match_pattern?(pattern, text)
       if pattern.start_with?('/') && pattern.end_with?('/') && pattern.length >= 2
-        Regexp.new(pattern[1..-2]).match?(text)
+        Regexp.new(pattern[1..-2]).match?(text) # steep:ignore
+      elsif pattern.count('*?[{').zero?
+        File.fnmatch?("*#{pattern.tr('/', '#')}*", text, File::FNM_EXTGLOB)
       else
         File.fnmatch?(pattern.tr('/', '#'), text, File::FNM_EXTGLOB)
       end
@@ -85,9 +87,9 @@ module Docscribe
     # Nested hashes are merged recursively; non-hash values are replaced.
     #
     # @private
-    # @param [Hash] hash1 base hash
-    # @param [Hash, nil] hash2 override hash
-    # @return [Hash]
+    # @param [Hash<Object, Object>] hash1 base hash
+    # @param [Hash<Object, Object>, nil] hash2 override hash
+    # @return [Hash<Object, Object>]
     def deep_merge(hash1, hash2)
       return hash1 unless hash2
 

data/lib/docscribe/config.rb

@@ -7,17 +7,15 @@ require 'psych'
 module Docscribe
   # Application configuration with deep-merge defaults and overrides.
   class Config
-    # Raw config hash after deep-merging user config with defaults.
-    #
     # @!attribute [r] raw
-    #   @return [Hash]
+    #   @return [Hash<String, Object>]
     attr_reader :raw
 
     # Create a configuration object from a raw config hash.
     #
     # Missing keys are filled from {DEFAULT} via deep merge.
     #
-    # @param [Hash, nil] raw user-provided config hash
+    # @param [Hash<String, Object>] raw user-provided config hash
     # @return [void]
     def initialize(raw = {})
       @raw = deep_merge(DEFAULT, raw || {})

data/lib/docscribe/infer/ast_walk.rb

@@ -11,7 +11,7 @@ module Docscribe
       # Yields each node exactly once, descending recursively through child nodes.
       # Non-AST values are ignored.
       #
-      # @note module_function: when included, also defines #walk (instance visibility: private)
+      # @note module_function: defines #walk (visibility: private)
       # @param [Parser::AST::Node, nil] node root AST node
       # @param [Proc] block visitor block
       # @return [void]

data/lib/docscribe/infer/literals.rb

@@ -17,7 +17,7 @@ module Docscribe
       #
       # If the node does not match a supported pattern, the fallback type is returned.
       #
-      # @note module_function: when included, also defines #type_from_literal (instance visibility: private)
+      # @note module_function: defines #type_from_literal (visibility: private)
       # @param [Parser::AST::Node, nil] node literal/value node
       # @param [String] fallback_type type returned when inference is uncertain
       # @return [String]
@@ -30,8 +30,7 @@ module Docscribe
 
       # Map a node type symbol to a known literal type name.
       #
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
+      # @note module_function: defines #literal_type_for (visibility: private)
       # @param [Symbol] type node type
       # @return [String, nil]
       def literal_type_for(type)
@@ -40,10 +39,8 @@ module Docscribe
 
       # Extract a constant name from a `:const` node.
       #
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [Parser::AST::Node] node
-      # @param [String] fallback_type
+      # @note module_function: defines #const_type_for (visibility: private)
+      # @param [Parser::AST::Node] node literal/value node
       # @param [String] _fallback_type fallback type string (unused here)
       # @return [String, nil]
       def const_type_for(node, _fallback_type)
@@ -54,10 +51,8 @@ module Docscribe
 
       # Extract a type from a `Foo.new` send node.
       #
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
-      # @param [Parser::AST::Node] node
-      # @param [String] fallback_type
+      # @note module_function: defines #send_new_type_for (visibility: private)
+      # @param [Parser::AST::Node] node literal/value node
       # @param [String] _fallback_type fallback type string (unused here)
       # @return [String, nil]
       def send_new_type_for(node, _fallback_type)

data/lib/docscribe/infer/names.rb

@@ -15,7 +15,7 @@ module Docscribe
       #
       # Returns nil for unsupported nodes.
       #
-      # @note module_function: when included, also defines #const_full_name (instance visibility: private)
+      # @note module_function: defines #const_full_name (visibility: private)
       # @param [Parser::AST::Node, nil] node constant-like AST node
       # @return [String, nil]
       def const_full_name(node)
@@ -31,8 +31,7 @@ module Docscribe
 
       # Build the fully qualified name from a `:const` node.
       #
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
+      # @note module_function: defines #build_const_full_name (visibility: private)
       # @param [Parser::AST::Node] node a `:const` node
       # @return [String]
       def build_const_full_name(node)

data/lib/docscribe/infer/params.rb

@@ -15,12 +15,11 @@ module Docscribe
       # - special-casing `options:` as `Hash` when enabled
       # - literal defaults via AST parsing
       #
-      # @note module_function: when included, also defines #infer_param_type (instance visibility: private)
+      # @note module_function: defines #infer_param_type (visibility: private)
       # @param [String] name parameter name as used internally (may include `*`, `**`, `&`, or trailing `:`)
-      # @param [String, nil] default_str source for the default value expression
+      # @param [String?] default_str source for the default value expression
       # @param [String] fallback_type type returned when inference is uncertain
       # @param [Boolean] treat_options_keyword_as_hash whether `options:` should
-      #   be treated specially as Hash
       # @return [String]
       def infer_param_type(name, default_str, fallback_type: FALLBACK_TYPE, treat_options_keyword_as_hash: true)
         prefix_param_type(name) || inferred_param_type(name, default_str, fallback_type,
@@ -29,8 +28,7 @@ module Docscribe
 
       # Return type for special parameter prefixes.
       #
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
+      # @note module_function: defines #prefix_param_type (visibility: private)
       # @param [String] name parameter name
       # @return [String, nil]
       def prefix_param_type(name)
@@ -43,12 +41,11 @@ module Docscribe
 
       # Infer type for a regular or keyword parameter with optional default.
       #
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
+      # @note module_function: defines #inferred_param_type (visibility: private)
       # @param [String] name parameter name
-      # @param [String, nil] default_str default expression source
-      # @param [String] fallback_type
-      # @param [Boolean] treat_options_keyword_as_hash
+      # @param [String?] default_str default expression source
+      # @param [String] fallback_type type returned when not special-cased
+      # @param [Boolean] treat_options_keyword_as_hash whether to treat 'options:' as Hash
       # @return [String]
       def inferred_param_type(name, default_str, fallback_type, treat_options_keyword_as_hash:)
         if name.end_with?(':') && default_str.nil?
@@ -65,7 +62,7 @@ module Docscribe
 
       # Return 'Hash' for a keyword parameter named 'options:' when special-cased, else fallback.
       #
-      # @note module_function: when included, also defines #options_keyword_type (instance visibility: private)
+      # @note module_function: defines #options_keyword_type (visibility: private)
       # @param [String] name parameter name
       # @param [Boolean] treat_options_keyword_as_hash whether to treat 'options:' as Hash
       # @param [String] fallback_type type returned when not special-cased
@@ -76,9 +73,9 @@ module Docscribe
 
       # Whether a keyword parameter named 'options:' with a hash default should be typed as Hash.
       #
-      # @note module_function: when included, also defines #options_hash_keyword? (instance visibility: private)
+      # @note module_function: defines #options_hash_keyword? (visibility: private)
       # @param [String] name parameter name
-      # @param [String, nil] default_str default expression source
+      # @param [String?] default_str default expression source
       # @param [String] type inferred type
       # @param [Boolean] treat_options_keyword_as_hash whether to treat 'options:' as Hash
       # @return [Boolean]
@@ -90,17 +87,18 @@ module Docscribe
       #
       # Returns nil if the expression is empty or cannot be parsed.
       #
-      # @note module_function: when included, also defines #parse_expr (instance visibility: private)
-      # @param [String, nil] src expression source
+      # @note module_function: defines #parse_expr (visibility: private)
+      # @param [String?] src expression source
       # @raise [Parser::SyntaxError]
-      # @return [Parser::AST::Node, nil]
+      # @return [Parser::AST::Node, nil] if Parser::SyntaxError
+      # @return [nil] if Parser::SyntaxError
       def parse_expr(src)
         return nil if src.nil? || src.strip.empty?
 
         buffer = Parser::Source::Buffer.new('(param)')
         buffer.source = src
         Docscribe::Parsing.parse_buffer(buffer)
-      rescue Parser::SyntaxError
+      rescue Parser::SyntaxError # steep:ignore
         nil
       end
     end

data/lib/docscribe/infer/raises.rb

@@ -16,7 +16,7 @@ module Docscribe
       #
       # Returns unique exception names in discovery order.
       #
-      # @note module_function: when included, also defines #infer_raises_from_node (instance visibility: private)
+      # @note module_function: defines #infer_raises_from_node (visibility: private)
       # @param [Parser::AST::Node] node method or expression node to inspect
       # @return [Array<String>]
       def infer_raises_from_node(node)
@@ -41,8 +41,7 @@ module Docscribe
       # - `Foo` => `["Foo"]`
       # - `[Foo, Bar]` => `["Foo", "Bar"]`
       #
-      # @note module_function: when included, also defines
-      #   #exception_names_from_rescue_list (instance visibility: private)
+      # @note module_function: defines #exception_names_from_rescue_list (visibility: private)
       # @param [Parser::AST::Node, nil] exc_list rescue exception list node
       # @return [Array<String>]
       def exception_names_from_rescue_list(exc_list)
@@ -57,8 +56,7 @@ module Docscribe
 
       # Collect exception names from a `raise` or `fail` send node.
       #
-      # @note module_function: when included, also defines # (instance visibility: private)
-      # @private
+      # @note module_function: defines #collect_send_raise (visibility: private)
       # @param [Array<String>] raises accumulator
       # @param [Parser::AST::Node] node send node
       # @return [void]