Class: Docscribe::Config

Inherits:
Object
  • Object
show all
Defined in:
lib/docscribe/config.rb,
lib/docscribe/config/rbs.rb,
lib/docscribe/config/emit.rb,
lib/docscribe/config/utils.rb,
lib/docscribe/config/loader.rb,
lib/docscribe/config/plugin.rb,
lib/docscribe/config/sorbet.rb,
lib/docscribe/config/sorting.rb,
lib/docscribe/config/defaults.rb,
lib/docscribe/config/template.rb,
lib/docscribe/config/filtering.rb

Overview

File and method include/exclude filtering.

Constant Summary collapse

DEFAULT =

Default configuration values used when no ‘docscribe.yml` is present or when specific keys are missing from user config.

These defaults define:

  • which documentation tags are emitted

  • default generated text

  • type inference behavior

  • method / file filtering

  • optional RBS integration

  • optional Sorbet integration

{
  'emit' => {
    'header' => false,
    'include_default_message' => true,
    'include_param_documentation' => true,
    'param_tags' => true,
    'return_tag' => true,
    'visibility_tags' => true,
    'raise_tags' => true,
    'rescue_conditional_returns' => true,
    'attributes' => false
  },
  'doc' => {
    'default_message' => 'Method documentation.',
    'param_tag_style' => 'type_name',
    'param_documentation' => 'Param documentation.',
    'sort_tags' => true,
    'tag_order' => %w[todo note api private protected param option yieldparam raise return]
  },
  'methods' => {
    'instance' => {
      'public' => {}, #: Hash[String, untyped]
      'protected' => {}, #: Hash[String, untyped]
      'private' => {} #: Hash[String, untyped]
    },
    'class' => {
      'public' => {}, #: Hash[String, untyped]
      'protected' => {}, #: Hash[String, untyped]
      'private' => {} #: Hash[String, untyped]
    }
  },
  'inference' => {
    'fallback_type' => 'Object',
    'nil_as_optional' => true,
    'treat_options_keyword_as_hash' => true
  },
  'filter' => {
    'visibilities' => %w[public protected private],
    'scopes' => %w[instance class],
    'include' => [], #: Array[String]
    'exclude' => [], #: Array[String]
    'files' => {
      'include' => [], #: Array[String]
      'exclude' => ['spec']
    }
  },
  'rbs' => {
    'enabled' => false,
    'collection' => false,
    'sig_dirs' => ['sig'],
    'collection_dirs' => [], #: Array[String]
    'collapse_generics' => false,
    'warn_missing_collection' => true,
    'collapse_object_generics' => false
  },
  'sorbet' => {
    'enabled' => false,
    'rbi_dirs' => ['sorbet/rbi', 'rbi'],
    'collapse_generics' => false
  },
  'keep_descriptions' => false,
  'skip_anonymous_block_params' => false,
  'plugins' => {
    'require' => [] #: Array[String]
  }
}.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(raw = {}) ⇒ void

Create a configuration object from a raw config hash.

Missing keys are filled from DEFAULT via deep merge.

Parameters:

  • raw (Hash<String, Object>) (defaults to: {}) —

    user-provided config hash



20
21
22
 
# File 'lib/docscribe/config.rb', line 20

def initialize(raw = {})
  @raw = deep_merge(DEFAULT, raw || {})
end

Instance Attribute Details

#raw ⇒ Object (readonly)

Returns the value of attribute raw.



12
13
14
 
# File 'lib/docscribe/config.rb', line 12

def raw
  @raw
end

Class Method Details

.default_yaml ⇒ String

Return the default YAML template used by ‘docscribe init`.

The template documents the most common CLI workflows and all supported configuration sections with comments.

Returns:

  • (String) 


12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/docscribe/config/template.rb', line 12

def self.default_yaml
  <<~YAML
    ---
    # Docscribe configuration file
    #
    # Docscribe works without this file — create it only for customization.
    #
    # Quick start:
    #   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
      header: false                       # +MyClass#foo+ -> ReturnType
      param_tags: true                    # @param tags
      return_tag: true                    # @return tag
      visibility_tags: true               # @private / @protected
      raise_tags: true                    # @raise tags
      rescue_conditional_returns: true    # @return [Type] if Error
      attributes: false                   # @!attribute for attr_*

      # Placeholder text for generated docs
      include_default_message: true       # "Method documentation."
      include_param_documentation: true   # "Param documentation."

    doc:
      # Default text and formatting
      default_message: "Method documentation."
      param_documentation: "Param documentation."
      param_tag_style: "type_name"        # "type_name" or "name_type"
      sort_tags: true
      tag_order: ["todo", "note", "api", "private", "protected", "param", "option", "yieldparam", "raise", "return"]

    inference:
      # Type inference behavior
      fallback_type: "Object"             # when uncertain
      nil_as_optional: true               # String | nil => String?
      treat_options_keyword_as_hash: true # options: keyword => Hash

    filter:
      # Which methods and files to process
      # Method format: "Container#method" (instance) or "Container.method" (class)
      # Supports globs ("*#initialize") and regex ("/^MyApp::.*$/")
      include: []
      exclude: []
      visibilities: ["public", "protected", "private"]
      scopes: ["instance", "class"]

      files:
        # File paths relative to project root (globs or /regex/)
        include: []
        exclude: ["spec"]

    methods:
      # Override defaults per scope and visibility.
      # Empty {} means "use values from `doc` section".
      #
      # Example:
      #   instance:
      #     public:
      #       default_message: "Public API."
      #     private:
      #       return_tag: false
      instance:
        public: {}
        protected: {}
        private: {}
      class:
        public: {}
        protected: {}
        private: {}

    rbs:
      # Use RBS signatures for better types (requires `gem "rbs"`)
      enabled: false
      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

    # 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:
      #   require:
      #     - ./docscribe_plugins
      #     - docscribe-rails-associations
      require: []
  YAML
end

.load(path = nil) ⇒ Docscribe::Config

Load Docscribe configuration from YAML.

Resolution order:

  • explicit ‘path`, if it exists

  • ‘docscribe.yml` in the current directory, if present

  • otherwise defaults only

Parameters:

  • path (String?) (defaults to: nil) —

    optional config path

Returns:



15
16
17
18
19
20
21
22
23
 
# File 'lib/docscribe/config/loader.rb', line 15

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)
end

.safe_load_compat(yaml, filename: nil) ⇒ Hash<String, Object>, Object

Safely load YAML from a string across Psych API versions.

Parameters:

  • yaml (String) —

    YAML document

  • filename (String?) (defaults to: nil) —

    optional filename for diagnostics

Returns:

  • (Hash<String, Object>) —

    if ArgumentError

  • (Object) —

    if ArgumentError

Raises:

  • (ArgumentError) 


52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/docscribe/config/loader.rb', line 52

def self.safe_load_compat(yaml, filename: nil)
  pclasses = [] #: Array[String]
  psymbols = [] #: Array[Symbol]
  Psych.safe_load( # steep:ignore
    yaml,
    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) # steep:ignore
end

.safe_load_file_compat(path) ⇒ Hash<String, Object>

Safely load YAML from a file across Ruby/Psych versions.

Uses ‘YAML.safe_load_file` when available, otherwise falls back to reading the file and calling safe_load_compat.

Parameters:

  • path (String) —

    file path

Returns:

  • (Hash<String, Object>) 


32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/docscribe/config/loader.rb', line 32

def self.safe_load_file_compat(path)
  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)
    safe_load_compat(yaml, filename: path) || {} #: Hash[String, untyped]
  end
end

Instance Method Details

#append_sorbet_providers(providers, source:, file:) ⇒ void

This method returns an undefined value.

Append Sorbet-based providers to the list.

Parameters:

  • providers (Array<Object>) —

    provider list to populate

  • source (String) —

    Ruby source being rewritten

  • file (String) —

    source name for diagnostics



31
32
33
34
35
36
 
# File 'lib/docscribe/config/sorbet.rb', line 31

def append_sorbet_providers(providers, source:, file:)
  return unless sorbet_enabled?

  providers << sorbet_source_provider(source, file)
  providers << sorbet_rbi_provider
end

#build_provider_chain(providers) ⇒ Docscribe::Types::ProviderChain?

Build the provider chain from a non-empty list, or return nil.

Parameters:

  • providers (Array<Object>) —

    provider list to chain

Returns:



60
61
62
63
64
65
66
 
# File 'lib/docscribe/config/sorbet.rb', line 60

def build_provider_chain(providers)
  providers = providers.compact
  return nil if providers.empty?

  require 'docscribe/types/provider_chain'
  Docscribe::Types::ProviderChain.new(*providers)
end

#core_rbs_provider ⇒ Docscribe::Types::RBS::Provider?

Core rbs provider

Returns:



29
30
31
32
33
 
# File 'lib/docscribe/config/rbs.rb', line 29

def core_rbs_provider
  return nil unless ruby_supports_rbs?

  @core_rbs_provider ||= build_core_rbs_provider
end

#default_message(scope, visibility) ⇒ String

Default text inserted into generated doc blocks, taking per-scope and per-visibility overrides into account.

Parameters:

  • scope (Symbol) —

    :instance or :class

  • visibility (Symbol) —

    :public, :protected, or :private

Returns:

  • (String) 


71
72
73
74
75
76
77
78
79
80
 
# File 'lib/docscribe/config/emit.rb', line 71

def default_message(scope, visibility)
  method_override_str(
    scope,
    visibility,
    'default_message',
    default: raw.dig('doc', 'default_message') ||
             DEFAULT.dig('doc', 'default_message') ||
             'Method documentation.'
  )
end

#emit_attributes? ⇒ Boolean

Whether to emit YARD ‘@!attribute` docs for `attr_*` macros.

Returns:

  • (Boolean) 


46
47
48
 
# File 'lib/docscribe/config/emit.rb', line 46

def emit_attributes?
  fetch_bool(%w[emit attributes], false)
end

#emit_header? ⇒ Boolean

Whether to emit method header lines such as:

# +MyClass#foo+ -> Integer

Returns:

  • (Boolean) 


10
11
12
 
# File 'lib/docscribe/config/emit.rb', line 10

def emit_header?
  fetch_bool(%w[emit header], true)
end

#emit_param_tags? ⇒ Boolean

Whether to emit ‘@param` tags.

Returns:

  • (Boolean) 


17
18
19
 
# File 'lib/docscribe/config/emit.rb', line 17

def emit_param_tags?
  fetch_bool(%w[emit param_tags], true)
end

#emit_raise_tags? ⇒ Boolean

Whether to emit inferred ‘@raise` tags.

Returns:

  • (Boolean) 


31
32
33
 
# File 'lib/docscribe/config/emit.rb', line 31

def emit_raise_tags?
  fetch_bool(%w[emit raise_tags], true)
end

#emit_rescue_conditional_returns? ⇒ Boolean

Whether to emit conditional rescue-return tags like:

# @return [String] if FooError

Returns:

  • (Boolean) 


39
40
41
 
# File 'lib/docscribe/config/emit.rb', line 39

def emit_rescue_conditional_returns?
  fetch_bool(%w[emit rescue_conditional_returns], true)
end

#emit_return_tag?(scope, visibility) ⇒ Boolean

Whether to emit the ‘@return` tag for a method, taking per-scope and per-visibility overrides into account.

Parameters:

  • scope (Symbol) —

    :instance or :class

  • visibility (Symbol) —

    :public, :protected, or :private

Returns:

  • (Boolean) 


56
57
58
59
60
61
62
63
 
# File 'lib/docscribe/config/emit.rb', line 56

def emit_return_tag?(scope, visibility)
  method_override_bool(
    scope,
    visibility,
    'return_tag',
    default: fetch_bool(%w[emit return_tag], true)
  )
end

#emit_visibility_tags? ⇒ Boolean

Whether to emit visibility tags such as ‘@private` and `@protected`.

Returns:

  • (Boolean) 


24
25
26
 
# File 'lib/docscribe/config/emit.rb', line 24

def emit_visibility_tags?
  fetch_bool(%w[emit visibility_tags], true)
end

#expand_directory_shorthand(pattern) ⇒ Array<String>

Expand a directory-like pattern into a recursive glob when appropriate.

Examples:

  • ‘“spec/”` => `“spec/*/”`

  • ‘“spec”` => `“spec/*/”` if `spec` exists as a directory

Parameters:

  • pattern (String) —

    file pattern to expand

Returns:

  • (Array<String>) 


91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/docscribe/config/filtering.rb', line 91

def expand_directory_shorthand(pattern)
  pat = pattern.dup

  if pat.end_with?('/')
    ["#{pat}**/*"]
  elsif !pat.match?(/[*?\[]|{/) && File.directory?(pat)
    ["#{pat}/**/*"]
  else
    [pat]
  end
end

#fallback_type ⇒ String

Fallback type used when inference cannot determine a more specific type.

Returns:

  • (String) 


85
86
87
88
89
 
# File 'lib/docscribe/config/emit.rb', line 85

def fallback_type
  raw.dig('inference', 'fallback_type') ||
    DEFAULT.dig('inference', 'fallback_type') ||
    'Object'
end

#file_match_pattern?(pattern, path) ⇒ Boolean

Match a file path against a single configured file filter.

Supports:

  • ‘/regex/`

  • globs

  • recursive glob shorthand normalization

Parameters:

  • pattern (String) —

    file filter pattern

  • path (String) —

    file path to test

Returns:

  • (Boolean) 


122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/docscribe/config/filtering.rb', line 122

def file_match_pattern?(pattern, path)
  if pattern.start_with?('/') && pattern.end_with?('/') && pattern.length >= 2
    return Regexp.new(pattern[1..-2]).match?(path) # steep:ignore
  end

  patterns_to_try = [pattern]
  patterns_to_try << pattern.gsub('/**/', '/') if pattern.include?('/**/')

  patterns_to_try.any? do |pat|
    File.fnmatch?(pat, path, File::FNM_EXTGLOB | File::FNM_DOTMATCH | File::FNM_PATHNAME)
  end
end

#file_matches_any?(patterns, path) ⇒ Boolean

Check whether a file path matches any configured file pattern.

Parameters:

  • patterns (Array<String>) —

    file filter patterns

  • path (String) —

    file path to test

Returns:

  • (Boolean) 


108
109
110
 
# File 'lib/docscribe/config/filtering.rb', line 108

def file_matches_any?(patterns, path)
  patterns.any? { |pat| file_match_pattern?(pat, path) }
end

#filter_exclude_patterns ⇒ Array<String>

Exclude method filter patterns.

Returns:

  • (Array<String>) 


153
154
155
156
 
# File 'lib/docscribe/config/filtering.rb', line 153

def filter_exclude_patterns
  Array(raw.dig('filter', 'exclude') ||
        DEFAULT.dig('filter', 'exclude')).map(&:to_s).reject(&:empty?) # steep:ignore
end

#filter_include_patterns ⇒ Array<String>

Include method filter patterns.

Returns:

  • (Array<String>) 


161
162
163
164
 
# File 'lib/docscribe/config/filtering.rb', line 161

def filter_include_patterns
  Array(raw.dig('filter', 'include') ||
        DEFAULT.dig('filter', 'include')).map(&:to_s).reject(&:empty?) # steep:ignore
end

#filter_scopes ⇒ Array<String>

Allowed method scopes from config/defaults.

Returns:

  • (Array<String>) 


138
139
140
 
# File 'lib/docscribe/config/filtering.rb', line 138

def filter_scopes
  Array(raw.dig('filter', 'scopes') || DEFAULT.dig('filter', 'scopes')).map(&:to_s) # steep:ignore
end

#filter_visibilities ⇒ Array<String>

Allowed method visibilities from config/defaults.

Returns:

  • (Array<String>) 


145
146
147
148
 
# File 'lib/docscribe/config/filtering.rb', line 145

def filter_visibilities
  Array(raw.dig('filter', 'visibilities') ||
        DEFAULT.dig('filter', 'visibilities')).map(&:to_s) # steep:ignore
end

#include_default_message? ⇒ Boolean

Whether to include the default placeholder line:

# Method documentation.

Returns:

  • (Boolean) 


131
132
133
 
# File 'lib/docscribe/config/emit.rb', line 131

def include_default_message?
  fetch_bool(%w[emit include_default_message], true)
end

#include_param_documentation? ⇒ Boolean

Whether to append placeholder text to generated @param tags:

# @param [String] name Param documentation.

Returns:

  • (Boolean) 


139
140
141
 
# File 'lib/docscribe/config/emit.rb', line 139

def include_param_documentation?
  fetch_bool(%w[emit include_param_documentation], true)
end

#keep_descriptions? ⇒ Boolean

Whether to preserve existing @param/@return descriptions in aggressive mode.

Returns:

  • (Boolean) 


146
147
148
 
# File 'lib/docscribe/config/emit.rb', line 146

def keep_descriptions?
  fetch_bool(%w[keep_descriptions], false)
end

#load_file_patterns ⇒ (Array<String>, Array<String>)

Load normalized file include/exclude patterns from config.

Returns:

  • ((Array<String>, Array<String>)) 


26
27
28
29
 
# File 'lib/docscribe/config/filtering.rb', line 26

def load_file_patterns
  files = raw.dig('filter', 'files') || {}
  [normalize_file_patterns(files['include']), normalize_file_patterns(files['exclude'])]
end

#load_plugins! ⇒ void

This method returns an undefined value.

Load and register plugins declared under ‘plugins.require` in config.

Each entry is expanded relative to the current working directory and passed to ‘require`. Registration is expected to happen inside the required file via Plugin::Registry.register.

Loading failures are non-fatal: a warning is printed and the run continues without the plugin.

Raises:

  • (LoadError) 


17
18
19
20
21
22
23
24
25
26
27
28
 
# File 'lib/docscribe/config/plugin.rb', line 17

def load_plugins!
  paths = Array(raw.dig('plugins', 'require')).compact #: Array[String]
  return if paths.empty?

  require 'docscribe/plugin'

  paths.each do |path|
    require File.expand_path(path)
  rescue LoadError => e
    warn "Docscribe: could not load plugin #{path.inspect}: #{e.message}"
  end
end

#nil_as_optional? ⇒ Boolean

Whether unions involving nil should be rendered as optional types.

For example, ‘String, nil` may become `String?` depending on formatter behavior.

Returns:

  • (Boolean) 


97
98
99
 
# File 'lib/docscribe/config/emit.rb', line 97

def nil_as_optional?
  fetch_bool(%w[inference nil_as_optional], true)
end

#normalize_file_patterns(list) ⇒ Array<String>

Normalize file filter patterns:

  • compact nils

  • stringify

  • remove empties

  • expand shorthand directory forms

Parameters:

  • list (Array<String>?) —

    raw pattern list

Returns:

  • (Array<String>) 


79
80
81
 
# File 'lib/docscribe/config/filtering.rb', line 79

def normalize_file_patterns(list)
  Array(list).compact.map(&:to_s).reject(&:empty?).flat_map { |pat| expand_directory_shorthand(pat) }.uniq
end

#param_documentation ⇒ String

Default generated parameter description text.

Returns:

  • (String) 


123
124
125
 
# File 'lib/docscribe/config/emit.rb', line 123

def param_documentation
  raw.dig('doc', 'param_documentation') || DEFAULT.dig('doc', 'param_documentation')
end

#param_tag_style ⇒ String

Param tag syntax style.

Supported values:

  • ‘“type_name”` => `@param [String] name`

  • ‘“name_type”` => `@param name [String]`

Returns:

  • (String) 


116
117
118
 
# File 'lib/docscribe/config/emit.rb', line 116

def param_tag_style
  raw.dig('doc', 'param_tag_style') || DEFAULT.dig('doc', 'param_tag_style')
end

#process_file?(path) ⇒ Boolean

Decide whether a file path should be processed based on ‘filter.files`.

File paths are matched relative to the current working directory when possible. Exclude rules win. If no include rules are configured, files are included by default.

Parameters:

  • path (String) —

    file path to test

Returns:

  • (Boolean) 


13
14
15
16
17
18
19
20
21
 
# File 'lib/docscribe/config/filtering.rb', line 13

def process_file?(path)
  include_patterns, exclude_patterns = load_file_patterns
  rel = relative_path(path)

  return false if file_matches_any?(exclude_patterns, rel)
  return true if include_patterns.empty?

  file_matches_any?(include_patterns, rel)
end

#process_method?(container:, scope:, visibility:, name:) ⇒ Boolean

Decide whether a method should be processed based on configured method filters.

Method IDs are normalized as:

  • instance method => ‘MyModule::MyClass#foo`

  • class method => ‘MyModule::MyClass.foo`

Exclude rules win. If no include rules are configured, methods are included by default subject to scope and visibility allow-lists.

Parameters:

  • container (String) —

    enclosing class/module name

  • scope (Symbol) —

    :instance or :class

  • visibility (Symbol) —

    :public, :protected, or :private

  • name (String, Symbol) —

    method name

Returns:

  • (Boolean) 


57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/docscribe/config/filtering.rb', line 57

def process_method?(container:, scope:, visibility:, name:)
  return false unless filter_scopes.include?(scope.to_s)
  return false unless filter_visibilities.include?(visibility.to_s)

  method_id = "#{container}#{scope == :instance ? '#' : '.'}#{name}"

  return false if matches_any?(filter_exclude_patterns, method_id)

  inc = filter_include_patterns
  return true if inc.empty?

  matches_any?(inc, method_id)
end

#rbs_enabled? ⇒ Boolean

Whether RBS integration is enabled.

Returns:

  • (Boolean) 


22
23
24
 
# File 'lib/docscribe/config/rbs.rb', line 22

def rbs_enabled?
  fetch_bool(%w[rbs enabled], false)
end

#rbs_provider ⇒ Docscribe::Types::RBS::Provider?

Return a memoized RBS provider if RBS integration is enabled and available.

If RBS cannot be loaded, this returns nil and Docscribe falls back to inference.

Returns:



12
13
14
15
16
17
 
# File 'lib/docscribe/config/rbs.rb', line 12

def rbs_provider
  return nil unless rbs_enabled?
  return nil unless ruby_supports_rbs?

  @rbs_provider ||= build_rbs_provider
end

#rbs_warn_missing_collection? ⇒ Boolean

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.

Returns:

  • (Boolean) 


41
42
43
 
# File 'lib/docscribe/config/rbs.rb', line 41

def rbs_warn_missing_collection?
  fetch_bool(%w[rbs warn_missing_collection], true)
end

#relative_path(path) ⇒ String, Object

Compute the relative path for filtering.

Parameters:

  • path (String) —

    file path to test

Returns:

  • (String) —

    if StandardError

  • (Object) —

    if StandardError

Raises:

  • (StandardError) 


37
38
39
40
41
 
# File 'lib/docscribe/config/filtering.rb', line 37

def relative_path(path)
  Pathname.new(path).expand_path.relative_path_from(Pathname.pwd).cleanpath.to_s
rescue StandardError
  path
end

#signature_provider_for(source:, file:) ⇒ Docscribe::Types::ProviderChain?

Build the effective external signature provider chain for a given source.

Provider precedence is:

  1. inline Sorbet signatures from the current source

  2. Sorbet RBI files

  3. RBS files

Returns nil when no external type provider is enabled or available.

Parameters:

  • source (String) —

    Ruby source being rewritten

  • file (String) —

    source name for diagnostics

Returns:



18
19
20
21
22
23
 
# File 'lib/docscribe/config/sorbet.rb', line 18

def signature_provider_for(source:, file:)
  providers = [] #: Array[untyped]
  append_sorbet_providers(providers, source: source, file: file)
  providers << rbs_provider if rbs_enabled?
  build_provider_chain(providers)
end

#skip_anonymous_block_params? ⇒ Boolean

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.

Returns:

  • (Boolean) 


156
157
158
 
# File 'lib/docscribe/config/emit.rb', line 156

def skip_anonymous_block_params?
  fetch_bool(%w[skip_anonymous_block_params], false)
end

#sorbet_collapse_generics? ⇒ Boolean

Whether generic Sorbet/RBI container types should be simplified.

Falls back to the RBS ‘collapse_generics` setting when Sorbet-specific config is not present.

Returns:

  • (Boolean) 


106
107
108
 
# File 'lib/docscribe/config/sorbet.rb', line 106

def sorbet_collapse_generics?
  fetch_bool(%w[sorbet collapse_generics], rbs_collapse_generics?)
end

#sorbet_enabled? ⇒ Boolean

Whether Sorbet support is enabled in config.

Returns:

  • (Boolean) 


89
90
91
 
# File 'lib/docscribe/config/sorbet.rb', line 89

def sorbet_enabled?
  fetch_bool(%w[sorbet enabled], false)
end

#sorbet_rbi_dirs ⇒ Array<String>

RBI directories searched by the Sorbet provider.

Returns:

  • (Array<String>) 


96
97
98
 
# File 'lib/docscribe/config/sorbet.rb', line 96

def sorbet_rbi_dirs
  Array(raw.dig('sorbet', 'rbi_dirs') || DEFAULT.dig('sorbet', 'rbi_dirs')).map(&:to_s) # steep:ignore
end

#sorbet_rbi_provider ⇒ Docscribe::Types::Sorbet::RBIProvider?

Return a memoized Sorbet RBI provider if Sorbet integration is enabled.

Returns:

Raises:

  • (LoadError) 


72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/docscribe/config/sorbet.rb', line 72

def sorbet_rbi_provider
  return nil unless sorbet_enabled?

  @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?
    )
  rescue LoadError
    nil
  end
end

#sorbet_source_provider(source, file) ⇒ Docscribe::Types::Sorbet::SourceProvider?

Build a Sorbet source provider (inline sigs).

Parameters:

  • source (String) —

    Ruby source being rewritten

  • file (String) —

    source name for diagnostics

Returns:

Raises:

  • (LoadError) 


45
46
47
48
49
50
51
52
53
54
 
# File 'lib/docscribe/config/sorbet.rb', line 45

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?
  )
rescue LoadError
  nil
end

#sort_tags? ⇒ Boolean

Whether sortable tag normalization is enabled for doc-like blocks.

Returns:

  • (Boolean) 


9
10
11
 
# File 'lib/docscribe/config/sorting.rb', line 9

def sort_tags?
  raw.dig('doc', 'sort_tags') != false
end

#tag_order ⇒ Array<String>

Configured sortable tag order.

Tags are normalized without a leading ‘@`.

Returns:

  • (Array<String>) 


18
19
20
21
22
 
# File 'lib/docscribe/config/sorting.rb', line 18

def tag_order
  Array(raw.dig('doc', 'tag_order') || DEFAULT.dig('doc', 'tag_order')).map do |t|
    t.to_s.sub(/\A@/, '') # steep:ignore
  end
end

#treat_options_keyword_as_hash? ⇒ Boolean

Whether keyword arguments named ‘options` / `options:` should be treated specially as Hash values during inference.

Returns:

  • (Boolean) 


105
106
107
 
# File 'lib/docscribe/config/emit.rb', line 105

def treat_options_keyword_as_hash?
  fetch_bool(%w[inference treat_options_keyword_as_hash], true)
end