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

.insert_comments(code, strategy: nil, rewrite: nil, merge: nil, config: nil, file: '(inline)') ⇒ 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

  • config (Docscribe::Config, nil) (defaults to: nil) —

    config object (defaults to loaded config)

  • file (String) (defaults to: '(inline)') —

    source name used for parser locations/debugging

Returns:

  • (String) 


48
49
50
51
52
53
54
55
56
57
 
# File 'lib/docscribe/inline_rewriter.rb', line 48

def insert_comments(code, strategy: nil, rewrite: nil, merge: nil, config: nil, file: '(inline)')
  strategy = normalize_strategy(strategy: strategy, rewrite: rewrite, merge: merge)

  rewrite_with_report(
    code,
    strategy: strategy,
    config: config,
    file: file
  )[:output]
end

.rewrite_with_report(code, strategy: nil, rewrite: nil, merge: nil, config: Docscribe::Config.new({}), core_rbs_provider: nil, file: '(inline)') ⇒ Hash

Rewrite source and return both output and structured change information.

The result hash includes:

  • ‘:output` => rewritten source

  • ‘:changes` => structured change records used by CLI explanation output

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

  • config (Docscribe::Config) (defaults to: Docscribe::Config.new({})) —

    config object (defaults to loaded config)

  • file (String) (defaults to: '(inline)') —

    source name used for parser locations/debugging

  • core_rbs_provider (nil) (defaults to: nil) —

    Param documentation.

Returns:

  • (Hash)

Raises:



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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/docscribe/inline_rewriter.rb', line 75

def rewrite_with_report(code, strategy: nil, rewrite: nil, merge: nil, config: Docscribe::Config.new({}),
                        core_rbs_provider: nil, file: '(inline)')
  strategy = normalize_strategy(strategy: strategy, rewrite: rewrite, merge: merge)
  validate_strategy!(strategy)

  buffer = Parser::Source::Buffer.new(file.to_s, source: code)
  ast = Docscribe::Parsing.parse_buffer(buffer)
  raise Docscribe::ParseError, "Failed to parse #{file}" unless ast

  config ||= Docscribe::Config.load
  signature_provider = build_signature_provider(config, code, file.to_s)
  unless core_rbs_provider
    if config.respond_to?(:core_rbs_provider)
      begin
        core_rbs_provider = config.core_rbs_provider
      rescue StandardError
        core_rbs_provider = nil
      end
    elsif config.respond_to?(:rbs_provider)
      begin
        core_rbs_provider = config.rbs_provider
      rescue StandardError
        core_rbs_provider = nil
      end
    end
  end

  collector = Docscribe::InlineRewriter::Collector.new(buffer)
  collector.process(ast)

  # Collect additional insertions from CollectorPlugins
  plugin_insertions = Docscribe::Plugin.run_collector_plugins(ast, buffer)

  method_insertions = collector.insertions
  attr_insertions = collector.respond_to?(:attr_insertions) ? collector.attr_insertions : []

  all = method_insertions.map { |i| [:method, i] } +
        attr_insertions.map { |i| [:attr, i] } +
        plugin_insertions.map { |i| [:plugin, i] }
  rewriter = Parser::Source::TreeRewriter.new(buffer)
  merge_inserts = Hash.new { |h, k| h[k] = [] }
  changes = []

  all.sort_by { |(kind, ins)| plugin_insertion_pos(kind, ins) }
     .reverse_each do |kind, ins|
    case kind
    when :method
      apply_method_insertion!(
        rewriter: rewriter,
        buffer: buffer,
        insertion: ins,
        config: config,
        signature_provider: signature_provider,
        core_rbs_provider: core_rbs_provider,
        strategy: strategy,
        changes: changes,
        file: file.to_s
      )
    when :attr
      apply_attr_insertion!(
        rewriter: rewriter,
        buffer: buffer,
        insertion: ins,
        config: config,
        signature_provider: signature_provider,
        strategy: strategy,
        merge_inserts: merge_inserts
      )
    when :plugin
      apply_plugin_insertion!(
        rewriter: rewriter,
        buffer: buffer,
        insertion: ins,
        strategy: strategy
      )
    end
  end

  apply_merge_inserts!(rewriter: rewriter, buffer: buffer, merge_inserts: merge_inserts)

  { output: rewriter.process, changes: changes }
end