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

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(buffer) ⇒ void

Create a collector for the given source buffer.

Parameters:

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

    source buffer for anchor location lookups



210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
 
# File 'lib/docscribe/inline_rewriter/collector.rb', line 210

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.



204
205
206
 
# File 'lib/docscribe/inline_rewriter/collector.rb', line 204

def attr_insertions
  @attr_insertions
end

#insertions ⇒ Object (readonly)

Returns the value of attribute insertions.



200
201
202
 
# File 'lib/docscribe/inline_rewriter/collector.rb', line 200

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



277
278
279
280
281
282
283
284
285
 
# File 'lib/docscribe/inline_rewriter/collector.rb', line 277

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) —

    an AST node

Returns:

  • (Parser::AST::Node) 


230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/docscribe/inline_rewriter/collector.rb', line 230

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) —

    an AST node

Returns:

  • (Parser::AST::Node) 


295
296
297
298
299
300
301
302
 
# File 'lib/docscribe/inline_rewriter/collector.rb', line 295

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) —

    an AST node

Returns:

  • (Parser::AST::Node) 


311
312
313
314
315
316
317
318
 
# File 'lib/docscribe/inline_rewriter/collector.rb', line 311

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) —

    an AST node

Returns:

  • (Parser::AST::Node) 


251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
 
# File 'lib/docscribe/inline_rewriter/collector.rb', line 251

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