Class: Docscribe::InlineRewriter::Collector

Inherits:
Parser::AST::Processor
  • Object
show all
Defined in:
lib/docscribe/inline_rewriter/collector.rb

Overview

AST walker that collects documentation insertion targets.

This is where Docscribe models Ruby scoping and visibility semantics so the doc generator can:

  • know whether a method is an instance method or class/module method (‘#` vs `.`)

  • add ‘@private` / `@protected` tags when appropriate

  • know the container name (‘A::B`) to show in `+A::B#foo+`

In addition to ‘private` / `protected` / `public` handling, Collector supports:

  • ‘module_function` inside modules

  • ‘extend self` inside modules

  • receiver-based containers (‘def Foo.bar`, `class << Foo`)

  • Sorbet-aware anchoring for methods with leading ‘sig` declarations

Defined Under Namespace

Classes: AttrInsertion, Insertion, VisibilityCtx

Constant Summary collapse

PROCESS_STMT_HANDLERS = 
{
  def: :process_def_stmt,
  defs: :process_defs_stmt,
  sclass: :process_sclass_stmt,
  send: :process_send_stmt
}.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(buffer) ⇒ Collector

Create a collector for the given source buffer.

Parameters:

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

    source buffer for anchor location lookups



199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
 
# File 'lib/docscribe/inline_rewriter/collector.rb', line 199

def initialize(buffer)
  super()
  @buffer = buffer
  @insertions = []
  @attr_insertions = []
  @name_stack = []

  # Track module-level state across reopened modules within the same file pass.
  # Example:
  #   module M; extend self; end
  #   module M; def foo; end; end  # => should still document foo as M.foo
  #
  # @type [Hash{String=>Hash}]
  @module_states = {} # { "M" => { extend_self: true } }
end

Instance Attribute Details

#attr_insertions ⇒ Object (readonly)

Returns the value of attribute attr_insertions.



193
194
195
 
# File 'lib/docscribe/inline_rewriter/collector.rb', line 193

def attr_insertions
  @attr_insertions
end

#insertions ⇒ Object (readonly)

Returns the value of attribute insertions.



189
190
191
 
# File 'lib/docscribe/inline_rewriter/collector.rb', line 189

def insertions
  @insertions
end

Instance Method Details

#on_casgn(node) ⇒ Parser::AST::Node

Process a constant assignment (e.g. ‘FOO = …` or `Foo::BAR = …`).

If the value is a ‘Struct.new` call, extracts attribute insertions first. Then continues processing child nodes.

Parameters:

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

    a ‘:casgn` node

Returns:

  • (Parser::AST::Node) —

    the original node



266
267
268
269
270
271
272
273
274
 
# File 'lib/docscribe/inline_rewriter/collector.rb', line 266

def on_casgn(node)
  return node if process_struct_casgn?(node)

  node.children.each do |child|
    process(child) if child.is_a?(Parser::AST::Node)
  end

  node
end

#on_class(node) ⇒ Parser::AST::Node

Enter a class body and collect documentation targets from its contents.

Parameters:

  • node (Parser::AST::Node)

Returns:

  • (Parser::AST::Node) 


219
220
221
222
223
224
225
226
227
228
229
230
231
 
# File 'lib/docscribe/inline_rewriter/collector.rb', line 219

def on_class(node)
  cname_node, super_node, body = *node
  @name_stack.push(const_name(cname_node))

  ctx = VisibilityCtx.new
  ctx.container_is_module = false

  process_struct_class(node, super_node)
  process_body(body, ctx)

  @name_stack.pop
  node
end

#on_def(node) ⇒ Parser::AST::Node

Enter a top-level method definition and collect it as a documentation target.

Top-level methods implicitly belong to Object. This handler ensures that def foo declared outside of any class or module is still picked up by the collector.

Parameters:

  • node (Parser::AST::Node)

Returns:

  • (Parser::AST::Node) 


284
285
286
287
288
289
290
291
 
# File 'lib/docscribe/inline_rewriter/collector.rb', line 284

def on_def(node)
  return node unless @name_stack.empty?

  ctx = VisibilityCtx.new
  ctx.container_is_module = false
  process_stmt(node, ctx)
  node
end

#on_defs(node) ⇒ Parser::AST::Node

Enter a top-level singleton method definition and collect it as a documentation target.

Handles the case of def self.foo declared at the top level, outside of any class or module body.

Parameters:

  • node (Parser::AST::Node)

Returns:

  • (Parser::AST::Node) 


300
301
302
303
304
305
306
307
 
# File 'lib/docscribe/inline_rewriter/collector.rb', line 300

def on_defs(node)
  return node unless @name_stack.empty?

  ctx = VisibilityCtx.new
  ctx.container_is_module = false
  process_stmt(node, ctx)
  node
end

#on_module(node) ⇒ Parser::AST::Node

Enter a module body and collect documentation targets from its contents.

This also carries ‘extend self` state across reopened modules in the same file.

Parameters:

  • node (Parser::AST::Node)

Returns:

  • (Parser::AST::Node) 


240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/docscribe/inline_rewriter/collector.rb', line 240

def on_module(node)
  cname_node, body = *node
  @name_stack.push(const_name(cname_node))

  container = current_container

  ctx = VisibilityCtx.new
  ctx.container_is_module = true
  ctx.extend_self = !!@module_states.dig(container, :extend_self)

  process_body(body, ctx)

  # If `extend self` is active for this module, document all instance defs as module methods (M.foo).
  persist_extend_self_state(ctx, container)

  @name_stack.pop
  node
end