docscribe 1.4.2 → 1.5.1

data/lib/docscribe/config/emit.rb

@@ -139,5 +139,22 @@ module Docscribe
     def include_param_documentation?
       fetch_bool(%w[emit include_param_documentation], true)
     end
+
+    # Whether to preserve existing @param/@return descriptions in aggressive mode.
+    #
+    # @return [Boolean]
+    def keep_descriptions?
+      fetch_bool(%w[keep_descriptions], false)
+    end
+
+    # Whether to skip @param generation for anonymous block arguments (&).
+    #
+    # Ruby 3.2+ allows `def foo(&)`. When enabled, no @param is generated
+    # for anonymous block parameters since they have no name to reference.
+    #
+    # @return [Boolean]
+    def skip_anonymous_block_params?
+      fetch_bool(%w[skip_anonymous_block_params], false)
+    end
   end
 end

data/lib/docscribe/config/filtering.rb

@@ -9,7 +9,6 @@ module Docscribe
     # Exclude rules win. If no include rules are configured, files are included by default.
     #
     # @param [String] path file path to test
-    # @raise [StandardError]
     # @return [Boolean]
     def process_file?(path)
       include_patterns, exclude_patterns = load_file_patterns
@@ -23,8 +22,7 @@ module Docscribe
 
     # Load normalized file include/exclude patterns from config.
     #
-    # @private
-    # @return [Array(Array<String>, Array<String>)] include_patterns, exclude_patterns
+    # @return [(Array<String>, Array<String>)]
     def load_file_patterns
       files = raw.dig('filter', 'files') || {}
       [normalize_file_patterns(files['include']), normalize_file_patterns(files['exclude'])]
@@ -32,10 +30,10 @@ module Docscribe
 
     # Compute the relative path for filtering.
     #
-    # @private
-    # @param [String] path
+    # @param [String] path file path to test
     # @raise [StandardError]
     # @return [String]
+    # @return [String] if StandardError
     def relative_path(path)
       Pathname.new(path).expand_path.relative_path_from(Pathname.pwd).cleanpath.to_s
     rescue StandardError
@@ -76,8 +74,7 @@ module Docscribe
     # - remove empties
     # - expand shorthand directory forms
     #
-    # @private
-    # @param [Array<String>, nil] list raw pattern list
+    # @param [Array<String>?] list raw pattern list
     # @return [Array<String>]
     def normalize_file_patterns(list)
       Array(list).compact.map(&:to_s).reject(&:empty?).flat_map { |pat| expand_directory_shorthand(pat) }.uniq
@@ -89,8 +86,7 @@ module Docscribe
     # - `"spec/"` => `"spec/**/*"`
     # - `"spec"` => `"spec/**/*"` if `spec` exists as a directory
     #
-    # @private
-    # @param [String] pattern
+    # @param [String] pattern file pattern to expand
     # @return [Array<String>]
     def expand_directory_shorthand(pattern)
       pat = pattern.dup
@@ -106,9 +102,8 @@ module Docscribe
 
     # Check whether a file path matches any configured file pattern.
     #
-    # @private
-    # @param [Array<String>] patterns
-    # @param [String] path
+    # @param [Array<String>] patterns file filter patterns
+    # @param [String] path file path to test
     # @return [Boolean]
     def file_matches_any?(patterns, path)
       patterns.any? { |pat| file_match_pattern?(pat, path) }
@@ -121,13 +116,12 @@ module Docscribe
     # - globs
     # - recursive glob shorthand normalization
     #
-    # @private
-    # @param [String] pattern
-    # @param [String] path
+    # @param [String] pattern file filter pattern
+    # @param [String] path file path to test
     # @return [Boolean]
     def file_match_pattern?(pattern, path)
       if pattern.start_with?('/') && pattern.end_with?('/') && pattern.length >= 2
-        return Regexp.new(pattern[1..-2]).match?(path)
+        return Regexp.new(pattern[1..-2]).match?(path) # steep:ignore
       end
 
       patterns_to_try = [pattern]
@@ -140,34 +134,33 @@ module Docscribe
 
     # Allowed method scopes from config/defaults.
     #
-    # @private
     # @return [Array<String>]
     def filter_scopes
-      Array(raw.dig('filter', 'scopes') || DEFAULT.dig('filter', 'scopes')).map(&:to_s)
+      Array(raw.dig('filter', 'scopes') || DEFAULT.dig('filter', 'scopes')).map(&:to_s) # steep:ignore
     end
 
     # Allowed method visibilities from config/defaults.
     #
-    # @private
     # @return [Array<String>]
     def filter_visibilities
-      Array(raw.dig('filter', 'visibilities') || DEFAULT.dig('filter', 'visibilities')).map(&:to_s)
+      Array(raw.dig('filter', 'visibilities') ||
+            DEFAULT.dig('filter', 'visibilities')).map(&:to_s) # steep:ignore
     end
 
     # Exclude method filter patterns.
     #
-    # @private
     # @return [Array<String>]
     def filter_exclude_patterns
-      Array(raw.dig('filter', 'exclude') || DEFAULT.dig('filter', 'exclude')).map(&:to_s).reject(&:empty?)
+      Array(raw.dig('filter', 'exclude') ||
+            DEFAULT.dig('filter', 'exclude')).map(&:to_s).reject(&:empty?) # steep:ignore
     end
 
     # Include method filter patterns.
     #
-    # @private
     # @return [Array<String>]
     def filter_include_patterns
-      Array(raw.dig('filter', 'include') || DEFAULT.dig('filter', 'include')).map(&:to_s).reject(&:empty?)
+      Array(raw.dig('filter', 'include') ||
+            DEFAULT.dig('filter', 'include')).map(&:to_s).reject(&:empty?) # steep:ignore
     end
   end
 end

data/lib/docscribe/config/loader.rb

@@ -10,16 +10,14 @@ 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]
-      if path && File.file?(path)
-        raw = safe_load_file_compat(path)
-      elsif File.file?('docscribe.yml')
-        raw = safe_load_file_compat('docscribe.yml')
-      end
-      new(raw)
+      resolved = path if path && File.file?(path)
+      resolved ||= 'docscribe.yml' if File.file?('docscribe.yml')
+      raw = safe_load_file_compat(resolved) if resolved
+      new(config_path: resolved, **raw) # steep:ignore
     end
 
     # Safely load YAML from a file across Ruby/Psych versions.
@@ -28,11 +26,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 +43,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>]
+    # @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 [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 [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,17 +37,18 @@ 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 [nil] if LoadError
     def sorbet_source_provider(source, file)
       require 'docscribe/types/sorbet/source_provider'
       Docscribe::Types::Sorbet::SourceProvider.new(
         source: source,
         file: file,
-        collapse_generics: sorbet_collapse_generics?
+        collapse_generics: sorbet_collapse_generics?,
+        collapse_object_generics: sorbet_collapse_object_generics?
       )
     rescue LoadError
       nil
@@ -57,8 +56,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
@@ -77,10 +75,9 @@ module Docscribe
 
       @sorbet_rbi_provider ||= begin
         require 'docscribe/types/sorbet/rbi_provider'
-        Docscribe::Types::Sorbet::RBIProvider.new(
-          rbi_dirs: sorbet_rbi_dirs,
-          collapse_generics: sorbet_collapse_generics?
-        )
+        Docscribe::Types::Sorbet::RBIProvider.new(rbi_dirs: sorbet_rbi_dirs,
+                                                  collapse_generics: sorbet_collapse_generics?,
+                                                  collapse_object_generics: sorbet_collapse_object_generics?)
       rescue LoadError
         nil
       end
@@ -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.
@@ -109,5 +106,14 @@ module Docscribe
     def sorbet_collapse_generics?
       fetch_bool(%w[sorbet collapse_generics], rbs_collapse_generics?)
     end
+
+    # Whether to collapse Object-typed generics in Sorbet types.
+    #
+    # Falls back to the RBS setting when Sorbet-specific config is not present.
+    #
+    # @return [Boolean]
+    def sorbet_collapse_object_generics?
+      fetch_bool(%w[sorbet collapse_object_generics], rbs_collapse_object_generics?)
+    end
   end
 end

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,13 +89,22 @@ 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
           enabled: false
           rbi_dirs: ["sorbet/rbi", "rbi"]
           collapse_generics: false
+          collapse_object_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

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,20 +7,24 @@ 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
 
+    # @!attribute [r] config_path
+    #   @return [String?]
+    attr_reader :config_path
+
     # 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 [String?] config_path optional path to the config file
+    # @param [Hash<String, Object>] raw user-provided config hash
     # @return [void]
-    def initialize(raw = {})
-      @raw = deep_merge(DEFAULT, raw || {})
+    def initialize(config_path: nil, **raw)
+      @raw = deep_merge(DEFAULT, raw)
+      @config_path = config_path
     end
   end
 end

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)