docscribe 1.6.1 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +258 -51
  3. data/exe/docscribe-client +26 -7
  4. data/lib/docscribe/cli/config_builder.rb +69 -8
  5. data/lib/docscribe/cli/config_dump.rb +88 -7
  6. data/lib/docscribe/cli/coverage.rb +5 -5
  7. data/lib/docscribe/cli/formatters/json.rb +74 -29
  8. data/lib/docscribe/cli/formatters/sarif.rb +20 -3
  9. data/lib/docscribe/cli/options.rb +36 -2
  10. data/lib/docscribe/cli/rbs_gen.rb +4 -4
  11. data/lib/docscribe/cli/run.rb +297 -52
  12. data/lib/docscribe/cli/update_types.rb +61 -17
  13. data/lib/docscribe/cli.rb +19 -13
  14. data/lib/docscribe/config/defaults.rb +2 -0
  15. data/lib/docscribe/config/plugin.rb +4 -4
  16. data/lib/docscribe/config/rbs.rb +30 -12
  17. data/lib/docscribe/config/sorbet.rb +3 -1
  18. data/lib/docscribe/config/template.rb +6 -0
  19. data/lib/docscribe/config/utils.rb +15 -0
  20. data/lib/docscribe/config/validation.rb +34 -0
  21. data/lib/docscribe/config.rb +35 -1
  22. data/lib/docscribe/infer/behavior.rb +13 -13
  23. data/lib/docscribe/infer/params.rb +2 -2
  24. data/lib/docscribe/infer/raises.rb +5 -6
  25. data/lib/docscribe/infer/returns.rb +1642 -151
  26. data/lib/docscribe/infer.rb +7 -7
  27. data/lib/docscribe/inline_rewriter/doc_builder.rb +551 -102
  28. data/lib/docscribe/inline_rewriter.rb +367 -98
  29. data/lib/docscribe/plugin/registry.rb +1 -0
  30. data/lib/docscribe/server/base.rb +73 -21
  31. data/lib/docscribe/server/client.rb +20 -11
  32. data/lib/docscribe/server/daemon.rb +209 -23
  33. data/lib/docscribe/server/protocol.rb +4 -4
  34. data/lib/docscribe/types/primitive.rb +160 -0
  35. data/lib/docscribe/types/rbs/provider.rb +5 -2
  36. data/lib/docscribe/types/sorbet/base_provider.rb +33 -1
  37. data/lib/docscribe/types/yard/formatter.rb +35 -6
  38. data/lib/docscribe/types/yard/parser.rb +32 -22
  39. data/lib/docscribe/types/yard/repair.rb +142 -0
  40. data/lib/docscribe/types/yard/validator.rb +131 -0
  41. data/lib/docscribe/validator/generic_compatibility.rb +698 -0
  42. data/lib/docscribe/validator/type_mismatch_validator.rb +287 -0
  43. data/lib/docscribe/version.rb +1 -1
  44. metadata +9 -3
@@ -40,7 +40,7 @@ module Docscribe
40
40
  # @param [Symbol?] strategy :safe or :aggressive
41
41
  # @param [Boolean?] rewrite compatibility alias for aggressive strategy
42
42
  # @param [Boolean?] merge compatibility alias for safe strategy
43
- # @param [Object] options additional keyword arguments forwarded to rewrite_with_report
43
+ # @param [Hash] options additional keyword arguments forwarded to rewrite_with_report
44
44
  # @return [String]
45
45
  def insert_comments(code, strategy: nil, rewrite: nil, merge: nil, **options)
46
46
  strategy = normalize_strategy(strategy: strategy, rewrite: rewrite, merge: merge)
@@ -54,8 +54,8 @@ module Docscribe
54
54
  # @param [Symbol?] strategy :safe or :aggressive
55
55
  # @param [Boolean?] rewrite compatibility alias for aggressive strategy
56
56
  # @param [Boolean?] merge compatibility alias for safe strategy
57
- # @param [Object] options additional keyword arguments forwarded to downstream helpers
58
- # @return [Hash<Symbol, String, Array<Hash<Symbol, Object>>>]
57
+ # @param [Hash] options additional keyword arguments forwarded to downstream helpers
58
+ # @return [Hash<Symbol, String, Array<Docscribe::InlineRewriter::changeRecord>>]
59
59
  def rewrite_with_report(code, strategy: nil, rewrite: nil, merge: nil, **options)
60
60
  strategy = normalize_strategy(strategy: strategy, rewrite: rewrite, merge: merge)
61
61
  validate_strategy!(strategy)
@@ -72,7 +72,7 @@ module Docscribe
72
72
  #
73
73
  # @param [Parser::Source::Buffer] buffer the source buffer being rewritten
74
74
  # @param [Parser::AST::Node] ast the parsed AST of the source code
75
- # @return [Hash<Symbol, Object>]
75
+ # @return [Docscribe::InlineRewriter::pipeline]
76
76
  def build_rewrite_pipeline(buffer, ast)
77
77
  all = collect_insertions(buffer, ast)
78
78
  method_overrides_by_pos = {} #: Hash[Integer, untyped]
@@ -87,26 +87,90 @@ module Docscribe
87
87
 
88
88
  # Dispatch rewrite insertions
89
89
  #
90
- # @param [Hash<Symbol, Object>] pipeline the pipeline hash with rewriter, insertions, and tracking state
90
+ # @param [Docscribe::InlineRewriter::pipeline] pipeline the pipeline hash with rewriter, insertions, and tracking state
91
91
  # @param [Parser::Source::Buffer] buffer the source buffer being rewritten
92
- # @param [Object] options additional kwargs (config, signature_provider, core_rbs_provider, strategy, file)
92
+ # @param [Hash] options additional kwargs (config, signature_provider, core_rbs_provider, strategy, file)
93
93
  # @return [void]
94
94
  def dispatch_rewrite_insertions(pipeline, buffer, **options)
95
95
  pipeline[:all].sort_by { |(kind, ins)| plugin_insertion_pos(kind, ins) }
96
96
  .reverse_each do |kind, ins|
97
- method_name = :"dispatch_#{kind}_insertion"
98
- send(method_name, ins, pipeline, buffer, **options) if respond_to?(method_name, true)
97
+ dispatch_single_insertion(kind, ins, pipeline, buffer, **options)
99
98
  end
100
99
 
101
100
  apply_merge_inserts!(rewriter: pipeline[:rewriter], buffer: buffer, merge_inserts: pipeline[:merge_inserts])
102
101
  end
103
102
 
103
+ # Dispatch a single insertion, isolating per-method failures.
104
+ #
105
+ # A crash while documenting one method (e.g., unexpected AST shape)
106
+ # must not discard warnings for the rest of the file: the error is
107
+ # reported to stderr and the remaining insertions still apply.
108
+ #
109
+ # @param [Symbol] kind insertion kind (:method, :attr, :plugin)
110
+ # @param [Object] ins the insertion object
111
+ # @param [Docscribe::InlineRewriter::pipeline] pipeline the pipeline hash with rewriter, insertions, and tracking state
112
+ # @param [Parser::Source::Buffer] buffer the source buffer being rewritten
113
+ # @param [Hash] options additional kwargs (config, signature_provider, core_rbs_provider, strategy, file)
114
+ # @raise [StandardError]
115
+ # @return [void]
116
+ # @return [Object] if StandardError
117
+ def dispatch_single_insertion(kind, ins, pipeline, buffer, **options)
118
+ method_name = :"dispatch_#{kind}_insertion"
119
+ return unless respond_to?(method_name, true)
120
+
121
+ send(method_name, ins, pipeline, buffer, **options)
122
+ rescue StandardError => e
123
+ warn_insertion_error(kind, ins, options[:file], e)
124
+ end
125
+
126
+ # Report a skipped insertion to stderr without interrupting the rewrite.
127
+ #
128
+ # @param [Symbol] kind insertion kind (:method, :attr, :plugin)
129
+ # @param [Object] ins the insertion object
130
+ # @param [String, nil] file the file being rewritten
131
+ # @param [StandardError] error the rescued error
132
+ # @return [void]
133
+ def warn_insertion_error(kind, ins, file, error)
134
+ warn "Docscribe: skipping #{insertion_label(kind, ins)} in #{file}: #{error.class}: #{error.message}"
135
+ end
136
+
137
+ # Human-readable label for an insertion used in skip warnings.
138
+ #
139
+ # @param [Symbol] kind insertion kind (:method, :attr, :plugin)
140
+ # @param [Object] ins the insertion object
141
+ # @return [String] label like "method foo at line 12"
142
+ def insertion_label(kind, ins)
143
+ node = insertion_node(ins)
144
+ name = node ? SourceHelpers.node_name(node) : nil
145
+ line = node_line(node)
146
+ label = name ? "#{kind} #{name}" : kind.to_s
147
+ line ? "#{label} at line #{line}" : label
148
+ end
149
+
150
+ # Extract the AST node from an insertion when available.
151
+ #
152
+ # @param [Object] ins the insertion object
153
+ # @return [Parser::AST::Node, nil] the node or nil
154
+ def insertion_node(ins)
155
+ ins.respond_to?(:node) ? ins.node : nil
156
+ end
157
+
158
+ # Source line of a node expression when available.
159
+ #
160
+ # @param [Parser::AST::Node, nil] node an AST node
161
+ # @return [Integer, nil] 1-based line number or nil
162
+ def node_line(node)
163
+ loc = node&.loc
164
+ expr = loc&.expression
165
+ expr&.line
166
+ end
167
+
104
168
  # Dispatch method insertion
105
169
  #
106
170
  # @param [Docscribe::InlineRewriter::Collector::Insertion] ins the attribute insertion object
107
- # @param [Hash<Symbol, Object>] pipeline the pipeline hash with rewriter, insertions, and tracking state
171
+ # @param [Docscribe::InlineRewriter::pipeline] pipeline the pipeline hash with rewriter, insertions, and tracking state
108
172
  # @param [Parser::Source::Buffer] buffer the source buffer
109
- # @param [Object] options the full keyword options hash
173
+ # @param [Hash] options the full keyword options hash
110
174
  # @return [void]
111
175
  def dispatch_method_insertion(ins, pipeline, buffer, **options)
112
176
  pos = plugin_insertion_pos(:method, ins)
@@ -124,9 +188,9 @@ module Docscribe
124
188
  # Dispatch attr insertion
125
189
  #
126
190
  # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins the attribute insertion object
127
- # @param [Hash<Symbol, Object>] pipeline the pipeline hash with rewriter, insertions, and tracking state
191
+ # @param [Docscribe::InlineRewriter::pipeline] pipeline the pipeline hash with rewriter, insertions, and tracking state
128
192
  # @param [Parser::Source::Buffer] buffer the source buffer
129
- # @param [Object] options the full keyword options hash
193
+ # @param [Hash] options the full keyword options hash
130
194
  # @return [void]
131
195
  def dispatch_attr_insertion(ins, pipeline, buffer, **options)
132
196
  apply_attr_insertion!(
@@ -138,10 +202,10 @@ module Docscribe
138
202
 
139
203
  # Dispatch plugin insertion
140
204
  #
141
- # @param [Hash<Symbol, Object>] ins the attribute insertion object
142
- # @param [Hash<Symbol, Object>] pipeline the pipeline hash with rewriter, insertions, and tracking state
205
+ # @param [Docscribe::InlineRewriter::pluginInsertion] ins the attribute insertion object
206
+ # @param [Docscribe::InlineRewriter::pipeline] pipeline the pipeline hash with rewriter, insertions, and tracking state
143
207
  # @param [Parser::Source::Buffer] buffer the source buffer
144
- # @param [Object] options the full keyword options hash
208
+ # @param [Hash] options the full keyword options hash
145
209
  # @return [void]
146
210
  def dispatch_plugin_insertion(ins, pipeline, buffer, **options)
147
211
  apply_plugin_insertion!(
@@ -158,7 +222,7 @@ module Docscribe
158
222
  # @param [String] code the Ruby source code string to parse and rewrite
159
223
  # @param [Hash<Symbol, Object>] options hash containing :config, :file, and :core_rbs_provider
160
224
  # @raise [Docscribe::ParseError]
161
- # @return [Hash<Symbol, Docscribe::Config, String, Parser::Source::Buffer, Parser::AST::Node, Docscribe::Types::ProviderChain, nil, Object, nil>] rewrite environment with keys
225
+ # @return [Hash<Symbol, Docscribe::Config, String, Parser::Source::Buffer, Parser::AST::Node, Docscribe::Types::ProviderChain, nil, Docscribe::Types::RBS::Provider, nil>] rewrite environment with keys
162
226
  # :config, :file, :buffer, :ast, :core_rbs_provider
163
227
  def setup_rewrite_env(code, options)
164
228
  config = options[:config] || Docscribe::Config.load
@@ -177,9 +241,9 @@ module Docscribe
177
241
  #
178
242
  # @private
179
243
  # @param [Docscribe::Config] config the active Docscribe::Config
180
- # @param [Object, nil] core_rbs_provider optional externally-provided core RBS provider
244
+ # @param [Docscribe::Types::RBS::Provider, nil] core_rbs_provider optional externally-provided core RBS provider
181
245
  # @raise [StandardError]
182
- # @return [Object, nil]
246
+ # @return [Docscribe::Types::RBS::Provider, nil]
183
247
  # @return [nil] if StandardError
184
248
  def load_core_rbs_provider(config, core_rbs_provider)
185
249
  core_rbs_provider || (config.respond_to?(:core_rbs_provider) ? config.core_rbs_provider : nil)
@@ -193,7 +257,7 @@ module Docscribe
193
257
  # @private
194
258
  # @param [Parser::Source::Buffer] buffer the source buffer to collect insertions from
195
259
  # @param [Parser::AST::Node] ast the parsed AST to traverse for collection
196
- # @return [Array<Object>]
260
+ # @return [Array<Docscribe::InlineRewriter::insertionPair>]
197
261
  def collect_insertions(buffer, ast)
198
262
  collector = Docscribe::InlineRewriter::Collector.new(buffer)
199
263
  collector.process(ast)
@@ -208,10 +272,10 @@ module Docscribe
208
272
  # Deduplicate insertions
209
273
  #
210
274
  # @private
211
- # @param [Array<(Symbol, Object)>] insertions insertions to deduplicate
212
- # @param [Hash<Integer, Hash<Symbol, Object>>, nil?] method_overrides_by_pos method-level overrides keyed
275
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] insertions insertions to deduplicate
276
+ # @param [Hash<Integer, Docscribe::InlineRewriter::methodOverride>?] method_overrides_by_pos method-level overrides keyed
213
277
  # by insertion position
214
- # @return [Array<(Symbol, Object)>]
278
+ # @return [Array<Docscribe::InlineRewriter::insertionPair>]
215
279
  def deduplicate_insertions(insertions, method_overrides_by_pos: nil)
216
280
  group_by_position(insertions).each_with_object([]) do |(pos, items), result|
217
281
  process_dedup_group(pos, items, result, method_overrides_by_pos)
@@ -222,9 +286,9 @@ module Docscribe
222
286
  #
223
287
  # @private
224
288
  # @param [Integer] pos the source begin_pos for the group
225
- # @param [Array<(Symbol, Object)>] items grouped items to process
226
- # @param [Array<(Symbol, Object)>] result accumulated result array
227
- # @param [Hash<Integer, Hash<Symbol, Object>>, nil] method_overrides_by_pos hash mapping position to method
289
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] items grouped items to process
290
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] result accumulated result array
291
+ # @param [Hash<Integer, Docscribe::InlineRewriter::methodOverride>, nil] method_overrides_by_pos hash mapping position to method
228
292
  # override data
229
293
  # @return [void]
230
294
  def process_dedup_group(pos, items, result, method_overrides_by_pos)
@@ -243,8 +307,8 @@ module Docscribe
243
307
  # Group by position
244
308
  #
245
309
  # @private
246
- # @param [Array<(Symbol, Object)>] insertions insertions to group
247
- # @return [Hash<Integer, Array<(Symbol, Object)>>]
310
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] insertions insertions to group
311
+ # @return [Hash<Integer, Array<Docscribe::InlineRewriter::insertionPair>>]
248
312
  def group_by_position(insertions)
249
313
  groups = {} #: Hash[Integer, untyped]
250
314
  insertions.each do |kind, ins|
@@ -257,8 +321,8 @@ module Docscribe
257
321
  # Find override items
258
322
  #
259
323
  # @private
260
- # @param [Array<(Symbol, Object)>] plugin_items plugin items to check
261
- # @return [Array<(Symbol, Object)>]
324
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] plugin_items plugin items to check
325
+ # @return [Array<Docscribe::InlineRewriter::insertionPair>]
262
326
  def find_override_items(plugin_items)
263
327
  plugin_items.select do |_k, ins|
264
328
  ins.is_a?(Hash) && ins[:method_override].is_a?(Hash)
@@ -268,10 +332,10 @@ module Docscribe
268
332
  # Handle override case
269
333
  #
270
334
  # @private
271
- # @param [Array<(Symbol, Object)>] result accumulated result array
272
- # @param [Array<(Symbol, Object)>] items all items in group
273
- # @param [Array<(Symbol, Object)>] override_items override plugin items
274
- # @param [Hash<Integer, Hash<Symbol, Object>>, nil] method_overrides_by_pos hash mapping position to
335
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] result accumulated result array
336
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] items all items in group
337
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] override_items override plugin items
338
+ # @param [Hash<Integer, Docscribe::InlineRewriter::methodOverride>, nil] method_overrides_by_pos hash mapping position to
275
339
  # method override data
276
340
  # @param [Integer] pos the source position of the conflict
277
341
  # @return [void]
@@ -288,11 +352,11 @@ module Docscribe
288
352
  # Deduplicate items
289
353
  #
290
354
  # @private
291
- # @param [Array<(Symbol, Object)>] items all items in group
292
- # @param [Array<(Symbol, Object)>] plugin_items plugin items in group
355
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] items all items in group
356
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] plugin_items plugin items in group
293
357
  # @param [Integer] pos the source position of the conflict
294
- # @param [Array<(Symbol, Object)>] _method_items method items in group
295
- # @return [Array<(Symbol, Object)>]
358
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] _method_items method items in group
359
+ # @return [Array<Docscribe::InlineRewriter::insertionPair>]
296
360
  def deduplicate_items(items, plugin_items, pos, _method_items)
297
361
  plugin_doc_items = plugin_items.select { |pair| plugin_doc_item?(pair) }
298
362
 
@@ -306,7 +370,7 @@ module Docscribe
306
370
  # Plugin doc item
307
371
  #
308
372
  # @private
309
- # @param [(Symbol, Object)] pair insertion pair to check
373
+ # @param [Docscribe::InlineRewriter::insertionPair] pair insertion pair to check
310
374
  # @return [Boolean]
311
375
  def plugin_doc_item?(pair)
312
376
  _k, ins = pair
@@ -316,10 +380,10 @@ module Docscribe
316
380
  # Deduplicate plugin doc case
317
381
  #
318
382
  # @private
319
- # @param [Array<(Symbol, Object)>] items all items in group
320
- # @param [Array<(Symbol, Object)>] plugin_doc_items plugin doc items
383
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] items all items in group
384
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] plugin_doc_items plugin doc items
321
385
  # @param [Integer] pos the source position of the conflict
322
- # @return [Array<(Symbol, Object)>]
386
+ # @return [Array<Docscribe::InlineRewriter::insertionPair>]
323
387
  def deduplicate_plugin_doc_case(items, plugin_doc_items, pos)
324
388
  items = items.reject { |k, _| k == :method }
325
389
  items = items.reject { |pair| override_or_plugin_method?(pair) }
@@ -336,7 +400,7 @@ module Docscribe
336
400
  # Override or plugin method
337
401
  #
338
402
  # @private
339
- # @param [(Symbol, Object)] pair insertion pair to check
403
+ # @param [Docscribe::InlineRewriter::insertionPair] pair insertion pair to check
340
404
  # @return [Boolean]
341
405
  def override_or_plugin_method?(pair)
342
406
  k, ins = pair
@@ -346,7 +410,7 @@ module Docscribe
346
410
  # Max plugin priority
347
411
  #
348
412
  # @private
349
- # @param [Array<(Symbol, Object)>] plugin_items plugin items to scan
413
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] plugin_items plugin items to scan
350
414
  # @return [Integer]
351
415
  def max_plugin_priority(plugin_items)
352
416
  plugin_items.map { |_k, ins| plugin_insertion_priority(ins) }.max || 0
@@ -355,9 +419,9 @@ module Docscribe
355
419
  # Filter lower priority plugins
356
420
  #
357
421
  # @private
358
- # @param [Array<(Symbol, Object)>] items items to filter
422
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] items items to filter
359
423
  # @param [Integer] threshold minimum priority threshold
360
- # @return [Array<(Symbol, Object)>]
424
+ # @return [Array<Docscribe::InlineRewriter::insertionPair>]
361
425
  def filter_lower_priority_plugins(items, threshold)
362
426
  items.select do |k, ins|
363
427
  k == :plugin && ins.is_a?(Hash) && ins[:doc] && plugin_insertion_priority(ins) < threshold
@@ -367,8 +431,8 @@ module Docscribe
367
431
  # Warn plugin conflict
368
432
  #
369
433
  # @private
370
- # @param [Array<(Symbol, Object)>] dropped dropped plugin items
371
- # @param [Array<(Symbol, Object)>] plugin_items kept plugin items
434
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] dropped dropped plugin items
435
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] plugin_items kept plugin items
372
436
  # @param [Integer] max_prio the maximum priority value
373
437
  # @param [Integer] pos the source position of the conflict
374
438
  # @return [void]
@@ -386,7 +450,7 @@ module Docscribe
386
450
  #
387
451
  # @private
388
452
  # @param [Integer] pos the source position of the conflict
389
- # @param [Array<(Symbol, Object)>] plugin_items plugin items for location
453
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] plugin_items plugin items for location
390
454
  # @return [String]
391
455
  def conflict_location_str(pos, plugin_items)
392
456
  line = plugin_insertion_line(plugin_items.first[1])
@@ -396,9 +460,9 @@ module Docscribe
396
460
  # Pick highest priority override insertion
397
461
  #
398
462
  # @private
399
- # @param [Array<(Symbol, Object)>] override_items override items to prioritize
463
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] override_items override items to prioritize
400
464
  # @param [Integer] pos begin_pos (used only for debug output)
401
- # @return [Hash<Symbol, Object>, nil] winning insertion hash (the one whose override will be applied)
465
+ # @return [Docscribe::InlineRewriter::pluginInsertion, nil] winning insertion hash (the one whose override will be applied)
402
466
  def pick_highest_priority_override_insertion(override_items, pos:)
403
467
  return nil if override_items.empty?
404
468
 
@@ -414,7 +478,7 @@ module Docscribe
414
478
  # Max plugin priority for
415
479
  #
416
480
  # @private
417
- # @param [Array<(Symbol, Object)>] override_items override items to evaluate
481
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] override_items override items to evaluate
418
482
  # @return [Integer]
419
483
  def max_plugin_priority_for(override_items)
420
484
  override_items.map { |_k, ins| plugin_insertion_priority(ins) }.max || 0
@@ -423,8 +487,8 @@ module Docscribe
423
487
  # Sort winners by order
424
488
  #
425
489
  # @private
426
- # @param [Array<(Symbol, Object)>] winners winning items to sort
427
- # @return [Array<(Symbol, Object)>]
490
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] winners winning items to sort
491
+ # @return [Array<Docscribe::InlineRewriter::insertionPair>]
428
492
  def sort_winners_by_order(winners)
429
493
  winners.sort_by do |_k, ins|
430
494
  order = ins.is_a?(Hash) ? ins[:__docscribe_plugin_order] : nil
@@ -435,7 +499,7 @@ module Docscribe
435
499
  # Warn override conflict
436
500
  #
437
501
  # @private
438
- # @param [Array<(Symbol, Object)>] winners_sorted sorted winning items
502
+ # @param [Array<Docscribe::InlineRewriter::insertionPair>] winners_sorted sorted winning items
439
503
  # @param [Integer] max_prio the maximum priority value
440
504
  # @param [Integer] pos the source position of the conflict
441
505
  # @return [void]
@@ -455,7 +519,7 @@ module Docscribe
455
519
  # Plugin insertion priority
456
520
  #
457
521
  # @private
458
- # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected
522
+ # @param [Docscribe::InlineRewriter::pluginInsertion, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected
459
523
  # method insertion (plugin hash or collected insertion object)
460
524
  # @raise [StandardError]
461
525
  # @return [Integer]
@@ -471,7 +535,7 @@ module Docscribe
471
535
  # Plugin insertion label
472
536
  #
473
537
  # @private
474
- # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected
538
+ # @param [Docscribe::InlineRewriter::pluginInsertion, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected
475
539
  # method insertion (plugin hash or collected insertion object)
476
540
  # @raise [StandardError]
477
541
  # @return [String]
@@ -488,7 +552,7 @@ module Docscribe
488
552
  # Plugin insertion line
489
553
  #
490
554
  # @private
491
- # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected
555
+ # @param [Docscribe::InlineRewriter::pluginInsertion, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected
492
556
  # method insertion (plugin hash or collected insertion object)
493
557
  # @raise [StandardError]
494
558
  # @return [Integer, nil]
@@ -507,7 +571,7 @@ module Docscribe
507
571
  #
508
572
  # @private
509
573
  # @param [Symbol] kind :method, :attr, or :plugin
510
- # @param [Hash<Symbol, Object>] ins insertion to locate
574
+ # @param [Docscribe::InlineRewriter::pluginInsertion] ins insertion to locate
511
575
  # @return [Integer]
512
576
  def plugin_insertion_pos(kind, ins)
513
577
  case kind
@@ -525,7 +589,7 @@ module Docscribe
525
589
  # @private
526
590
  # @param [Parser::Source::TreeRewriter] rewriter the TreeRewriter accumulating source transformations
527
591
  # @param [Parser::Source::Buffer] buffer the source buffer
528
- # @param [Hash<Symbol, Object>] insertion { anchor_node:, doc: }
592
+ # @param [Docscribe::InlineRewriter::pluginInsertion] insertion { anchor_node:, doc: }
529
593
  # @param [Symbol] strategy :safe or :aggressive rewrite mode
530
594
  # @param [Docscribe::Config] config the active configuration
531
595
  # @return [void]
@@ -725,9 +789,9 @@ module Docscribe
725
789
  # Apply method insertion
726
790
  #
727
791
  # @private
728
- # @param [Object] options kwargs with insertion, config, rewriter, buffer, strategy, changes, file, doc params
792
+ # @param [Hash] options kwargs with insertion, config, rewriter, buffer, strategy, changes, file, doc params
729
793
  # @return [void]
730
- def apply_method_insertion!(**options)
794
+ def apply_method_insertion!(**options) # rubocop:disable Metrics/AbcSize
731
795
  insertion = options[:insertion]
732
796
  config = options[:config]
733
797
  return unless method_insertion_allowed?(insertion, config)
@@ -735,6 +799,7 @@ module Docscribe
735
799
  anchor_bol_range, = method_bol_ranges(options[:buffer], insertion)
736
800
  params = build_method_insertion_params(insertion, config, options[:signature_provider],
737
801
  options[:core_rbs_provider], options[:method_override])
802
+ seed_declared_param_types!(options[:buffer], insertion, params, config, options[:strategy])
738
803
  extract_existing_descriptions!(options[:buffer], insertion, params, options[:strategy], config)
739
804
  doc = DocBuilder.build(insertion, **params) # steep:ignore
740
805
  dispatch_method_insertion_by_strategy!(anchor_bol_range, options, params, doc)
@@ -806,8 +871,8 @@ module Docscribe
806
871
  # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
807
872
  # @param [Docscribe::Config] config the active configuration
808
873
  # @param [Docscribe::Types::ProviderChain, nil] signature_provider RBS signature provider
809
- # @param [Object, nil] core_rbs_provider optional externally-provided core RBS provider
810
- # @param [Hash<Symbol, Object>, nil] method_override the raw override data
874
+ # @param [Docscribe::Types::RBS::Provider, nil] core_rbs_provider optional externally-provided core RBS provider
875
+ # @param [Docscribe::InlineRewriter::methodOverride, nil] method_override the raw override data
811
876
  # @return [Hash<Symbol, Object>]
812
877
  def build_method_insertion_params(insertion, config, signature_provider, core_rbs_provider, method_override)
813
878
  override = extract_method_override!(method_override)
@@ -821,7 +886,7 @@ module Docscribe
821
886
  #
822
887
  # @private
823
888
  # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
824
- # @param [Object] options keyword options
889
+ # @param [Hash] options keyword options
825
890
  # @return [Hash<Symbol, Hash<String, String>, nil, String, nil, Array<Docscribe::Plugin::Tag>>]
826
891
  def build_effective_params(insertion, **options)
827
892
  external_sig = resolve_external_signature(insertion, options[:signature_provider])
@@ -852,8 +917,8 @@ module Docscribe
852
917
  end
853
918
 
854
919
  # @private
855
- # @param [Object] insertion
856
- # @return [(Integer?, Array<Object>)]
920
+ # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion
921
+ # @return [(Integer?, Array<String>)]
857
922
  def extract_param_info(insertion)
858
923
  args = DocBuilder.extract_args_from_node(insertion.node)
859
924
  empty = [] #: Array[untyped]
@@ -873,10 +938,112 @@ module Docscribe
873
938
  DocBuilder.build_param_types_from_node(insertion.node, external_sig: external_sig, config: config)
874
939
  end
875
940
 
941
+ # Fill param types from `@param` tags already present in the source.
942
+ #
943
+ # A declared `@param` is only a fallback: it is a human comment and may lie,
944
+ # so it applies solely where inference left `Object`/`untyped`. Without it a
945
+ # param like `tag_order` stays `Object`, collapsing
946
+ # `map { |t| t.strip }.each_with_index.to_h` to `Hash<Object, ...>`.
947
+ #
948
+ # Safe mode only: aggressive mode deliberately re-infers param types over
949
+ # declared ones, and `validate_types` needs the declared type kept separate
950
+ # so it can report a mismatch.
951
+ #
952
+ # @private
953
+ # @param [Parser::Source::Buffer] buffer the source buffer
954
+ # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
955
+ # @param [Hash<Symbol, Object>] params insertion params
956
+ # @param [Docscribe::Config] config the active configuration
957
+ # @param [Symbol] strategy :safe or :aggressive rewrite mode
958
+ # @return [void]
959
+ def seed_declared_param_types!(buffer, insertion, params, config, strategy) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
960
+ return if strategy == :aggressive || config.validate_types?
961
+
962
+ declared = DocBuilder.parse_existing_doc_tags(
963
+ method_doc_comment_info(buffer, insertion)&.dig(:doc_lines) || []
964
+ )[:param_types]
965
+
966
+ # Invalid YARD types must reach the invalid-type fixer untouched.
967
+ declared = (declared || {}).select { |_name, type| valid_yard_type?(type) }
968
+ return if declared.empty?
969
+
970
+ current = params[:param_types] || {}
971
+ params[:param_types] = current.merge(declared) { |_name, inferred, decl| merge_param_type(inferred, decl) }
972
+ end
973
+
974
+ # Combine an inferred param type with a declared `@param` type.
975
+ #
976
+ # The declared type fills gaps and adds generic detail (`Array` ->
977
+ # `Array<String>`), but the AST wins a real conflict because it reflects
978
+ # what the code does, while a `@param` tag is a human comment that can lie.
979
+ #
980
+ # @private
981
+ # @param [String, nil] inferred type derived from the AST
982
+ # @param [String] declared type from the `@param` tag
983
+ # @return [String, nil]
984
+ def merge_param_type(inferred, declared)
985
+ return declared if inferred.nil? || unknown_type?(inferred)
986
+ return inferred if unknown_type?(declared)
987
+ return inferred unless same_base_type?(inferred, declared)
988
+
989
+ type_arity(declared) > type_arity(inferred) ? declared : inferred
990
+ end
991
+
992
+ # Whether two types name the same base type, ignoring generic arguments.
993
+ #
994
+ # @private
995
+ # @param [String] left first type
996
+ # @param [String] right second type
997
+ # @return [Boolean]
998
+ def same_base_type?(left, right)
999
+ base_type_name(left) == base_type_name(right)
1000
+ end
1001
+
1002
+ # Number of generic arguments carried by a type.
1003
+ #
1004
+ # @private
1005
+ # @param [String] type type string
1006
+ # @return [Integer]
1007
+ def type_arity(type)
1008
+ base_type_name(type) == type.to_s.strip ? 0 : 1
1009
+ end
1010
+
1011
+ # Base name of a type, with any generic arguments stripped.
1012
+ #
1013
+ # @private
1014
+ # @param [String] type type string
1015
+ # @return [String]
1016
+ def base_type_name(type)
1017
+ type.to_s.split('<', 2).first.to_s.strip
1018
+ end
1019
+
1020
+ # Whether a param type carries no usable information.
1021
+ #
1022
+ # @private
1023
+ # @param [String, nil] type param type string
1024
+ # @return [Boolean]
1025
+ def unknown_type?(type)
1026
+ type.nil? || %w[Object untyped nil].include?(type)
1027
+ end
1028
+
1029
+ # Whether a declared `@param` type is valid YARD and safe to reuse for inference.
1030
+ #
1031
+ # @private
1032
+ # @param [String, nil] type declared YARD type string
1033
+ # @raise [StandardError] when the YARD type validator fails on odd syntax
1034
+ # @return [Boolean]
1035
+ def valid_yard_type?(type)
1036
+ return false if type.nil? || type.strip.empty?
1037
+
1038
+ Docscribe::Types::Yard::Validator.valid?(type)
1039
+ rescue StandardError
1040
+ false
1041
+ end
1042
+
876
1043
  # Apply method insertion aggressive
877
1044
  #
878
1045
  # @private
879
- # @param [Object] options keyword options
1046
+ # @param [Hash] options keyword options
880
1047
  # @return [void]
881
1048
  def apply_method_insertion_aggressive!(**options)
882
1049
  rewriter = options[:rewriter]
@@ -907,7 +1074,7 @@ module Docscribe
907
1074
  # Apply method insertion safe
908
1075
  #
909
1076
  # @private
910
- # @param [Object] options keyword options
1077
+ # @param [Hash] options keyword options
911
1078
  # @return [void]
912
1079
  def apply_method_insertion_safe!(**options)
913
1080
  info = method_doc_comment_info(options[:buffer], options[:insertion])
@@ -922,7 +1089,7 @@ module Docscribe
922
1089
  # Apply method insertion safe with info
923
1090
  #
924
1091
  # @private
925
- # @param [Object] options keyword options
1092
+ # @param [Hash] options keyword options
926
1093
  # @return [void]
927
1094
  def apply_method_insertion_safe_with_info!(**options)
928
1095
  i = options[:info]
@@ -941,9 +1108,9 @@ module Docscribe
941
1108
  # @private
942
1109
  # @param [Parser::Source::TreeRewriter] rewriter the TreeRewriter accumulating source transformations
943
1110
  # @param [Parser::Source::Buffer] buffer the source buffer being rewritten
944
- # @param [Hash<Symbol, Object>] info hash containing existing doc comment block data
1111
+ # @param [Docscribe::InlineRewriter::docInfo] info hash containing existing doc comment block data
945
1112
  # @param [String] new_block the newly constructed replacement doc block string
946
- # @param [Object] rest additional kwargs (old_block, merge_result,
1113
+ # @param [Hash] rest additional kwargs (old_block, merge_result,
947
1114
  # @return [void]
948
1115
  def commit_safe_doc_outcome(rewriter, buffer, info, new_block, **rest)
949
1116
  handle_doc_replacement(rewriter, buffer, info, new_block,
@@ -969,9 +1136,9 @@ module Docscribe
969
1136
  # @private
970
1137
  # @param [Parser::Source::TreeRewriter] rewriter the TreeRewriter accumulating source transformations
971
1138
  # @param [Parser::Source::Buffer] buffer the source buffer being rewritten
972
- # @param [Hash<Symbol, Object>] info hash containing existing doc comment block data (start_pos, end_pos, lines)
1139
+ # @param [Docscribe::InlineRewriter::docInfo] info hash containing existing doc comment block data (start_pos, end_pos, lines)
973
1140
  # @param [String] new_block the newly constructed replacement doc block string
974
- # @param [Object] log_opts additional keyword arguments for logging and recording changes
1141
+ # @param [Hash] log_opts additional keyword arguments for logging and recording changes
975
1142
  # @return [void]
976
1143
  def handle_doc_replacement(rewriter, buffer, info, new_block, **log_opts)
977
1144
  range = Parser::Source::Range.new(buffer, info[:start_pos], info[:end_pos])
@@ -987,44 +1154,146 @@ module Docscribe
987
1154
  # Compute doc replacement
988
1155
  #
989
1156
  # @private
990
- # @param [Hash<Symbol, Object>] info existing doc info
1157
+ # @param [Docscribe::InlineRewriter::docInfo] info existing doc info
991
1158
  # @param [Array<String>] missing_lines new doc lines to add
992
- # @param [Object] options keyword options
1159
+ # @param [Hash] options keyword options
993
1160
  # @return [(Boolean, String, String)]
994
1161
  def compute_doc_replacement(info, missing_lines, **options)
995
1162
  dc = options[:config]
1163
+ filter = filter_for_missing(info, missing_lines)
996
1164
  sorted = Docscribe::InlineRewriter::DocBlock.merge(
997
1165
  info[:doc_lines], missing_lines: [], sort_tags: dc.sort_tags?, tag_order: dc.tag_order
998
1166
  )
999
1167
  merged = Docscribe::InlineRewriter::DocBlock.merge(
1000
- info[:doc_lines], missing_lines: missing_lines, sort_tags: dc.sort_tags?, tag_order: dc.tag_order
1168
+ info[:doc_lines], missing_lines: missing_lines, sort_tags: dc.sort_tags?, tag_order: dc.tag_order,
1169
+ filter_existing: filter
1001
1170
  )
1002
1171
  [sorted != info[:doc_lines], (info[:preserved_lines] + merged).join, info[:lines].join]
1003
1172
  end
1004
1173
 
1174
+ # Build filter for DocBlock.merge when missing lines replace existing invalid tags.
1175
+ #
1176
+ # @private
1177
+ # @param [Docscribe::InlineRewriter::docInfo] info parsed doc info from method_doc_comment_info
1178
+ # @param [Array<String>] missing_lines generated missing lines
1179
+ # @return [Hash<Symbol, Object>] filter for existing entries
1180
+ def filter_for_missing(info, missing_lines)
1181
+ filter = {} #: Hash[Symbol, untyped]
1182
+ doc_lines = Array(info[:doc_lines]) #: Array[String]
1183
+ filter[:return] = true if return_filter_needed?(doc_lines, missing_lines)
1184
+ names = param_names_for_filter(doc_lines, missing_lines)
1185
+ filter[:param_names] = names if names.any?
1186
+ filter
1187
+ end
1188
+
1189
+ # Whether return filter is needed.
1190
+ #
1191
+ # @private
1192
+ # @param [Array<String>] doc_lines existing doc lines
1193
+ # @param [Array<String>] missing_lines generated missing lines
1194
+ # @return [Boolean]
1195
+ def return_filter_needed?(doc_lines, missing_lines)
1196
+ doc_lines.any? { |l| l.include?('@return') } && missing_lines.any? { |l| l.include?('@return') }
1197
+ end
1198
+
1199
+ # Param names that need filtering.
1200
+ #
1201
+ # @private
1202
+ # @param [Array<String>] doc_lines existing doc lines
1203
+ # @param [Array<String>] missing_lines generated missing lines
1204
+ # @return [Array<String>]
1205
+ def param_names_for_filter(doc_lines, missing_lines)
1206
+ missing_names = missing_lines.filter_map { |l| extract_param_name_for_filter(l) }
1207
+ existing_names = doc_lines.filter_map { |l| extract_param_name_for_filter(l) }
1208
+ missing_names & existing_names
1209
+ end
1210
+
1211
+ # Extract param name from a generated @param line for filtering.
1212
+ #
1213
+ # @private
1214
+ # @param [String] line generated param line
1215
+ # @return [String, nil]
1216
+ def extract_param_name_for_filter(line)
1217
+ content = line.sub(/^\s*#\s*/, '')
1218
+ if (m = content.match(/@param\s+(\S+)\s+\[/))
1219
+ return m[1]
1220
+ elsif (m = content.match(/@param\s+\[/))
1221
+ rest = content[(m.end(0) - 1)..] # steep:ignore
1222
+ type_end = rest.index(']') # steep:ignore
1223
+ return rest[(type_end + 1)..].to_s.strip.split(/\s+/).first if type_end # steep:ignore
1224
+ end
1225
+
1226
+ nil
1227
+ end
1228
+
1005
1229
  # Log method doc changes
1006
1230
  #
1007
1231
  # @private
1008
1232
  # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
1009
1233
  # @param [Hash<Symbol, Object>] merge_result merge operation result
1010
- # @param [Object] rest additional keyword arguments forwarded to add_change
1234
+ # @param [Hash] rest additional keyword arguments forwarded to add_change
1011
1235
  # @return [void]
1012
1236
  def log_method_doc_changes!(insertion:, merge_result:, **rest)
1013
1237
  reason_specs = merge_result[:reasons] || []
1014
- type_mismatch_reasons = reason_specs.select { |r| %i[updated_param updated_return].include?(r[:type]) }
1238
+ return unless doc_changed?(rest, reason_specs)
1015
1239
 
1016
- return unless rest[:new_block] != rest[:old_block] || type_mismatch_reasons.any?
1240
+ log_reasons(reason_specs, insertion, rest)
1241
+ end
1017
1242
 
1018
- reason_specs.each do |reason|
1019
- add_change(changes: rest[:changes], type: reason[:type], insertion: insertion,
1020
- file: rest[:file], message: reason[:message], extra: reason[:extra] || {})
1021
- end
1243
+ # @private
1244
+ # @param [Hash<Symbol, Object>] rest
1245
+ # @param [Array<Hash<Symbol, Object>>] reason_specs
1246
+ # @return [Boolean]
1247
+ def doc_changed?(rest, reason_specs)
1248
+ rest[:new_block] != rest[:old_block] || type_mismatch_reasons?(reason_specs)
1249
+ end
1250
+
1251
+ # @private
1252
+ # @param [Array<Hash<Symbol, Object>>] reason_specs
1253
+ # @return [Boolean]
1254
+ def type_mismatch_reasons?(reason_specs)
1255
+ reason_specs.any? { |r| type_mismatch_type?(r[:type]) }
1256
+ end
1257
+
1258
+ # @private
1259
+ # @param [Symbol] type
1260
+ # @return [Boolean]
1261
+ def type_mismatch_type?(type)
1262
+ %i[updated_param updated_return invalid_type].include?(type)
1263
+ end
1264
+
1265
+ # @private
1266
+ # @param [Array<Hash<Symbol, Object>>] reason_specs
1267
+ # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion
1268
+ # @param [Hash<Symbol, Object>] rest
1269
+ # @return [void]
1270
+ def log_reasons(reason_specs, insertion, rest)
1271
+ reason_specs.each { |reason| log_single_reason(reason, insertion, rest) }
1272
+ end
1273
+
1274
+ # @private
1275
+ # @param [Hash<Symbol, Object>] reason
1276
+ # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion
1277
+ # @param [Hash<Symbol, Object>] rest
1278
+ # @return [void]
1279
+ def log_single_reason(reason, insertion, rest)
1280
+ add_change(changes: rest[:changes], type: reason[:type], insertion: insertion,
1281
+ file: rest[:file], message: reason[:message], extra: extra_for_reason(reason))
1282
+ end
1283
+
1284
+ # @private
1285
+ # @param [Hash<Symbol, Object>] reason
1286
+ # @return [Hash<Symbol, Object>]
1287
+ def extra_for_reason(reason)
1288
+ extra = (reason[:extra] || {}).dup
1289
+ extra[:source] = reason[:source] if reason[:source]
1290
+ extra
1022
1291
  end
1023
1292
 
1024
1293
  # Apply method insertion safe without info
1025
1294
  #
1026
1295
  # @private
1027
- # @param [Object] options keyword options
1296
+ # @param [Hash] options keyword options
1028
1297
  # @return [void]
1029
1298
  def apply_method_insertion_safe_without_info!(**options)
1030
1299
  rewriter = options[:rewriter]
@@ -1042,13 +1311,13 @@ module Docscribe
1042
1311
 
1043
1312
  # Filter options to keep only doc-building params for safe-without-info mode.
1044
1313
  # @private
1045
- # @param [Object] options the full options hash to filter
1314
+ # @param [Hash[Symbol, untyped]] options the full options hash to filter
1046
1315
  # @return [Object]
1047
1316
 
1048
1317
  # Add change
1049
1318
  #
1050
1319
  # @private
1051
- # @param [Object] options kwargs for change record (type, file, line, method, message, insertion, changes, extra)
1320
+ # @param [Hash] options kwargs for change record (type, file, line, method, message, insertion, changes, extra)
1052
1321
  # @return [void]
1053
1322
  def add_change(**options)
1054
1323
  changes = options[:changes]
@@ -1074,7 +1343,7 @@ module Docscribe
1074
1343
  # Apply attr insertion
1075
1344
  #
1076
1345
  # @private
1077
- # @param [Object] options kwargs (insertion, config, rewriter, buffer, strategy,
1346
+ # @param [Hash] options kwargs (insertion, config, rewriter, buffer, strategy,
1078
1347
  # @return [void]
1079
1348
  def apply_attr_insertion!(**options)
1080
1349
  config = options[:config]
@@ -1166,7 +1435,7 @@ module Docscribe
1166
1435
  # @param [Hash<Integer, Array<(Integer, String)>>] merge_inserts deferred merge inserts
1167
1436
  # @param [Docscribe::Config] config the active Docscribe::Config
1168
1437
  # @param [Docscribe::Types::ProviderChain, nil] signature_provider external RBS signature provider
1169
- # @return [void]
1438
+ # @return [Array<(Integer, String)>, nil]
1170
1439
  def merge_attr_additions!(insertion:, info:, merge_inserts:, config:, signature_provider:)
1171
1440
  additions = build_attr_merge_additions(ins: insertion, existing_lines: info[:lines],
1172
1441
  config: config, signature_provider: signature_provider)
@@ -1262,7 +1531,7 @@ module Docscribe
1262
1531
  end
1263
1532
 
1264
1533
  # @private
1265
- # @param [Object] ins
1534
+ # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins
1266
1535
  # @param [Array<String>] existing_lines
1267
1536
  # @param [String] indent
1268
1537
  # @param [Docscribe::Config] config
@@ -1282,7 +1551,7 @@ module Docscribe
1282
1551
  end
1283
1552
 
1284
1553
  # @private
1285
- # @param [Object] ins
1554
+ # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins
1286
1555
  # @param [Array<String>] existing_lines
1287
1556
  # @param [String] indent
1288
1557
  # @param [Docscribe::Config] config
@@ -1313,7 +1582,7 @@ module Docscribe
1313
1582
  #
1314
1583
  # @private
1315
1584
  # @param [Array<String>] lines array of existing doc comment lines
1316
- # @return [Hash<String, nil, Boolean>]
1585
+ # @return [Hash<String, Boolean>]
1317
1586
  def existing_attr_names(lines)
1318
1587
  names = {} #: Hash[String, bool]
1319
1588
 
@@ -1480,7 +1749,7 @@ module Docscribe
1480
1749
  # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins the attribute insertion object
1481
1750
  # @param [Symbol] name_sym the attribute name as a Symbol
1482
1751
  # @param [String] indent whitespace indentation prefix
1483
- # @param [Object] opts additional keyword arguments forwarded from build_attr_doc_lines
1752
+ # @param [Hash] opts additional keyword arguments forwarded from build_attr_doc_lines
1484
1753
  # @return [Array<String>]
1485
1754
  def build_single_attr_lines(ins, name_sym, indent:, **opts)
1486
1755
  cfg = opts[:config]
@@ -1500,7 +1769,7 @@ module Docscribe
1500
1769
  # @param [String] indent whitespace indentation prefix
1501
1770
  # @param [String] attr_type the resolved type string for the attribute
1502
1771
  # @param [Symbol] access the access level (:r, :w, or :rw)
1503
- # @return [void]
1772
+ # @return [Array<String>, nil]
1504
1773
  def append_attr_return_tag(lines, indent, attr_type, access)
1505
1774
  lines << "#{indent}# @return [#{attr_type}]" if %i[r rw].include?(access)
1506
1775
  end
@@ -1513,7 +1782,7 @@ module Docscribe
1513
1782
  # @param [String] attr_type the resolved type string for the attribute
1514
1783
  # @param [Symbol] access the access level (:r, :w, or :rw)
1515
1784
  # @param [Docscribe::Config] cfg the active Docscribe::Config
1516
- # @return [void]
1785
+ # @return [Array<String>, nil]
1517
1786
  def append_attr_param_tag(lines, indent, attr_type, access, cfg)
1518
1787
  return unless %i[w rw].include?(access)
1519
1788
 
@@ -1582,7 +1851,7 @@ module Docscribe
1582
1851
  # @param [String] code the source code being processed
1583
1852
  # @param [String] file the file name
1584
1853
  # @raise [StandardError]
1585
- # @return [Object, nil]
1854
+ # @return [Docscribe::Types::ProviderChain, Docscribe::Types::RBS::Provider, nil]
1586
1855
  # @return [Docscribe::Types::RBS::Provider, nil?] if StandardError
1587
1856
  def build_signature_provider(config, code, file)
1588
1857
  if config.respond_to?(:signature_provider_for)
@@ -1601,7 +1870,7 @@ module Docscribe
1601
1870
  # @private
1602
1871
  # @param [Parser::Source::Buffer] buffer the source buffer
1603
1872
  # @param [Docscribe::InlineRewriter::Collector::Insertion] insertion the collected method insertion
1604
- # @return [Hash<Symbol, Object>, nil] doc comment block info or nil
1873
+ # @return [Docscribe::InlineRewriter::docInfo, nil] doc comment block info or nil
1605
1874
  def method_doc_comment_info(buffer, insertion)
1606
1875
  anchor_bol_range, def_bol_range = method_bol_ranges(buffer, insertion)
1607
1876
 
@@ -1665,8 +1934,8 @@ module Docscribe
1665
1934
  # Extract method override
1666
1935
  #
1667
1936
  # @private
1668
- # @param [Hash<Symbol, Object>, nil] method_override the raw override data
1669
- # @return [Hash<Symbol, Object>] normalized override hash
1937
+ # @param [Docscribe::InlineRewriter::methodOverride, nil] method_override the raw override data
1938
+ # @return [Docscribe::InlineRewriter::methodOverride] normalized override hash
1670
1939
  def extract_method_override!(method_override)
1671
1940
  return {} unless method_override.is_a?(Hash)
1672
1941