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<Symbol, Object>

Build rewrite pipeline

Parameters:

  • buffer (Parser::Source::Buffer) —

    the source buffer being rewritten

  • ast (Parser::AST::Node) —

    the parsed AST of the source code

Returns:

  • (Hash<Symbol, Object>) 


76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/docscribe/inline_rewriter.rb', line 76

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) # steep:ignore
  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 attr insertion

Parameters:

  • ins (Docscribe::InlineRewriter::Collector::AttrInsertion) —

    the attribute insertion object

  • pipeline (Hash<Symbol, Object>) —

    the pipeline hash with rewriter, insertions, and tracking state

  • buffer (Parser::Source::Buffer) —

    the source buffer

  • options (Object) —

    the full keyword options hash



131
132
133
134
135
136
137
 
# File 'lib/docscribe/inline_rewriter.rb', line 131

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 method insertion

Parameters:

  • ins (Docscribe::InlineRewriter::Collector::Insertion) —

    the attribute insertion object

  • pipeline (Hash<Symbol, Object>) —

    the pipeline hash with rewriter, insertions, and tracking state

  • buffer (Parser::Source::Buffer) —

    the source buffer

  • options (Object) —

    the full keyword options hash



111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/docscribe/inline_rewriter.rb', line 111

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 plugin insertion

Parameters:

  • ins (Hash<Symbol, Object>) —

    the attribute insertion object

  • pipeline (Hash<Symbol, Object>) —

    the pipeline hash with rewriter, insertions, and tracking state

  • buffer (Parser::Source::Buffer) —

    the source buffer

  • options (Object) —

    the full keyword options hash



146
147
148
149
150
151
 
# File 'lib/docscribe/inline_rewriter.rb', line 146

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) ⇒ void

This method returns an undefined value.

Dispatch rewrite insertions

Parameters:

  • pipeline (Hash<Symbol, Object>) —

    the pipeline hash with rewriter, insertions, and tracking state

  • buffer (Parser::Source::Buffer) —

    the source buffer being rewritten

  • options (Object) —

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



94
95
96
97
98
99
100
101
102
 
# File 'lib/docscribe/inline_rewriter.rb', line 94

def dispatch_rewrite_insertions(pipeline, buffer, **options)
  pipeline[:all].sort_by { |(kind, ins)| plugin_insertion_pos(kind, ins) }
                .reverse_each do |kind, ins|
    method_name = :"dispatch_#{kind}_insertion"
    send(method_name, ins, pipeline, buffer, **options) if respond_to?(method_name, true)
  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

Insert comments

Parameters:

  • code (String) —

    Ruby source

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

    :safe or :aggressive

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

    compatibility alias for aggressive strategy

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

    compatibility alias for safe strategy

  • options (Object) —

    additional keyword arguments forwarded to rewrite_with_report

Returns:

  • (String) 


45
46
47
48
49
 
# File 'lib/docscribe/inline_rewriter.rb', line 45

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<Symbol, String, Array<Hash<Symbol, Object>>>

Rewrite with report

Parameters:

  • code (String) —

    Ruby source

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

    :safe or :aggressive

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

    compatibility alias for aggressive strategy

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

    compatibility alias for safe strategy

  • options (Object) —

    additional keyword arguments forwarded to downstream helpers

Returns:

  • (Hash<Symbol, String, Array<Hash<Symbol, Object>>>) 


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

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