Module: Docscribe::InlineRewriter

Defined in:
lib/docscribe/inline_rewriter.rb,
lib/docscribe/inline_rewriter/collector.rb,
lib/docscribe/inline_rewriter/doc_block.rb,
lib/docscribe/inline_rewriter/tag_sorter.rb,
lib/docscribe/inline_rewriter/doc_builder.rb,
lib/docscribe/inline_rewriter/source_helpers.rb

Overview

Rewrite Ruby source to insert or update inline YARD-style documentation.

Supported strategies:

  • ‘:safe`

    • insert missing docs

    • merge into existing doc-like blocks

    • normalize configured sortable tags

    • preserve existing prose and directives where possible

  • ‘:aggressive`

    • replace existing doc blocks with freshly generated docs

Compatibility note:

  • ‘merge: true` maps to `strategy: :safe`

  • ‘rewrite: true` maps to `strategy: :aggressive`

Defined Under Namespace

Modules: DocBlock, DocBuilder, SourceHelpers, TagSorter Classes: Collector

Class Method Summary collapse

Class Method Details

.build_rewrite_pipeline(buffer, ast) ⇒ Hash

Build the insertion pipeline: collector, plugin insertions, dedup, rewriter, merge_inserts, changes.

Parameters:

  • buffer (Object) —

    the source buffer being rewritten

  • ast (Object) —

    the parsed AST of the source code

Returns:

  • (Hash) 


81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/docscribe/inline_rewriter.rb', line 81

def build_rewrite_pipeline(buffer, ast)
  all = collect_insertions(buffer, ast)
  method_overrides_by_pos = {} #: Hash[Integer, untyped]
  all = deduplicate_insertions(all, method_overrides_by_pos: method_overrides_by_pos)
  rewriter = Parser::Source::TreeRewriter.new(buffer)
  merge_inserts = Hash.new { |h, k| h[k] = [] } #: Hash[Integer, untyped]
  changes = [] #: Array[untyped]

  { all: all, method_overrides_by_pos: method_overrides_by_pos, rewriter: rewriter,
    merge_inserts: merge_inserts, changes: changes }
end

.dispatch_attr_insertion(ins, pipeline, buffer, **options) ⇒ void

This method returns an undefined value.

Dispatch an attr insertion.

Parameters:

  • ins (Object)
  • pipeline (Hash)
  • buffer (Object)
  • options (Hash) 


141
142
143
144
145
146
147
 
# File 'lib/docscribe/inline_rewriter.rb', line 141

def dispatch_attr_insertion(ins, pipeline, buffer, **options)
  apply_attr_insertion!(
    rewriter: pipeline[:rewriter], buffer: buffer, insertion: ins,
    config: options[:config], signature_provider: options[:signature_provider],
    strategy: options[:strategy], merge_inserts: pipeline[:merge_inserts]
  )
end

.dispatch_method_insertion(ins, pipeline, buffer, **options) ⇒ void

This method returns an undefined value.

Dispatch a method insertion.

Parameters:

  • ins (Object)
  • pipeline (Hash)
  • buffer (Object)
  • options (Hash) 


120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/docscribe/inline_rewriter.rb', line 120

def dispatch_method_insertion(ins, pipeline, buffer, **options)
  pos = plugin_insertion_pos(:method, ins)
  method_override = pipeline[:method_overrides_by_pos][pos]

  apply_method_insertion!(
    rewriter: pipeline[:rewriter], buffer: buffer, insertion: ins,
    config: options[:config], signature_provider: options[:signature_provider],
    core_rbs_provider: options[:core_rbs_provider], strategy: options[:strategy],
    changes: pipeline[:changes], file: options[:file],
    method_override: method_override
  )
end

.dispatch_plugin_insertion(ins, pipeline, buffer, **options) ⇒ void

This method returns an undefined value.

Dispatch a plugin insertion.

Parameters:

  • ins (Object)
  • pipeline (Hash)
  • buffer (Object)
  • options (Hash) 


157
158
159
160
161
162
 
# File 'lib/docscribe/inline_rewriter.rb', line 157

def dispatch_plugin_insertion(ins, pipeline, buffer, **options)
  apply_plugin_insertion!(
    rewriter: pipeline[:rewriter], buffer: buffer, insertion: ins,
    strategy: options[:strategy], config: options[:config]
  )
end

.dispatch_rewrite_insertions(pipeline, buffer, **options) ⇒ Object

Dispatch all insertions to the appropriate handler.

Parameters:

  • pipeline (Object) —

    the pipeline hash with rewriter, insertions, and tracking state

  • buffer (Object) —

    the source buffer being rewritten

  • options (Hash) —

    additional kwargs (config, signature_provider, core_rbs_provider, strategy, file)

Returns:

  • (Object) 


99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/docscribe/inline_rewriter.rb', line 99

def dispatch_rewrite_insertions(pipeline, buffer, **options)
  pipeline[:all].sort_by { |(kind, ins)| plugin_insertion_pos(kind, ins) }
                .reverse_each do |kind, ins|
    case kind
    when :method then dispatch_method_insertion(ins, pipeline, buffer, **options)
    when :attr then dispatch_attr_insertion(ins, pipeline, buffer, **options)
    when :plugin then dispatch_plugin_insertion(ins, pipeline, buffer, **options)
    end
  end

  apply_merge_inserts!(rewriter: pipeline[:rewriter], buffer: buffer, merge_inserts: pipeline[:merge_inserts])
end

.insert_comments(code, strategy: nil, rewrite: nil, merge: nil, **options) ⇒ String

Rewrite source and return only the rewritten output string.

This is the main convenience entry point for library usage.

Parameters:

  • code (String) —

    Ruby source

  • strategy (Symbol, nil) (defaults to: nil) —

    :safe or :aggressive

  • rewrite (Boolean, nil) (defaults to: nil) —

    compatibility alias for aggressive strategy

  • merge (Boolean, nil) (defaults to: nil) —

    compatibility alias for safe strategy

  • options (Hash) —

    additional keyword arguments forwarded to rewrite_with_report

Returns:

  • (String) 


47
48
49
50
51
 
# File 'lib/docscribe/inline_rewriter.rb', line 47

def insert_comments(code, strategy: nil, rewrite: nil, merge: nil, **options)
  strategy = normalize_strategy(strategy: strategy, rewrite: rewrite, merge: merge)

  rewrite_with_report(code, strategy: strategy, **options)[:output]
end

.rewrite_with_report(code, strategy: nil, rewrite: nil, merge: nil, **options) ⇒ Hash

Rewrite source and return both output and structured change information.

Parameters:

  • code (String) —

    Ruby source

  • strategy (Symbol, nil) (defaults to: nil) —

    :safe or :aggressive

  • rewrite (Boolean, nil) (defaults to: nil) —

    compatibility alias for aggressive strategy

  • merge (Boolean, nil) (defaults to: nil) —

    compatibility alias for safe strategy

  • **options (Hash) —

    remaining options (config:, file:, core_rbs_provider:)

  • options (Hash) —

    additional keyword arguments forwarded to downstream helpers

Returns:

  • (Hash)

Raises:



64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/docscribe/inline_rewriter.rb', line 64

def rewrite_with_report(code, strategy: nil, rewrite: nil, merge: nil, **options)
  strategy = normalize_strategy(strategy: strategy, rewrite: rewrite, merge: merge)
  validate_strategy!(strategy)
  parsed = setup_rewrite_env(code, options)
  pipeline = build_rewrite_pipeline(parsed[:buffer], parsed[:ast])
  dispatch_rewrite_insertions(pipeline, parsed[:buffer],
                              config: parsed[:config], signature_provider: parsed[:signature_provider],
                              core_rbs_provider: parsed[:core_rbs_provider], strategy: strategy,
                              file: parsed[:file])
  { output: pipeline[:rewriter].process, changes: pipeline[:changes] }
end