Class: RDoc::Parser::Ruby::RDocVisitor

Inherits:

Prism::Visitor

• Object
• Prism::Visitor
• RDoc::Parser::Ruby::RDocVisitor

Defined in:

lib/rdoc/parser/ruby.rb

Overview

:nodoc:

Defined Under Namespace

Classes: MethodSignatureVisitor

Instance Method Summary

• #initialize(scanner, top_level, store) ⇒ RDocVisitor constructor

  A new instance of RDocVisitor.

• #visit_alias_method_node(node) ⇒ Object
• #visit_block_node(node) ⇒ Object
• #visit_call_node(node) ⇒ Object
• #visit_class_node(node) ⇒ Object
• #visit_constant_path_write_node(node) ⇒ Object
• #visit_constant_write_node(node) ⇒ Object
• #visit_def_node(node) ⇒ Object
• #visit_if_node(node) ⇒ Object (also: #visit_unless_node)
• #visit_module_node(node) ⇒ Object
• #visit_singleton_class_node(node) ⇒ Object

Constructor Details

#initialize(scanner, top_level, store) ⇒ RDocVisitor

Returns a new instance of RDocVisitor.

# File 'lib/rdoc/parser/ruby.rb', line 972

def initialize(scanner, top_level, store)
  @scanner = scanner
  @top_level = top_level
  @store = store
end

Instance Method Details

#visit_alias_method_node(node) ⇒ Object

# File 'lib/rdoc/parser/ruby.rb', line 1050

def visit_alias_method_node(node)
  return if @scanner.in_proc_block
  @scanner.process_comments_until(node.location.start_line - 1)
  return unless node.old_name.is_a?(Prism::SymbolNode) && node.new_name.is_a?(Prism::SymbolNode)
  @scanner.add_alias_method(node.old_name.value.to_s, node.new_name.value.to_s, node.location.start_line)
end

#visit_block_node(node) ⇒ Object

# File 'lib/rdoc/parser/ruby.rb', line 1042

def visit_block_node(node)
  @scanner.with_in_proc_block do
    # include, extend and method definition inside block are not documentable.
    # visibility methods and attribute definition methods should be ignored inside block.
    super
  end
end

#visit_call_node(node) ⇒ Object

# File 'lib/rdoc/parser/ruby.rb', line 992

def visit_call_node(node)
  @scanner.process_comments_until(node.location.start_line - 1)
  if node.receiver.nil?
    case node.name
    when :attr
      _visit_call_attr_reader_writer_accessor(node, 'R')
    when :attr_reader
      _visit_call_attr_reader_writer_accessor(node, 'R')
    when :attr_writer
      _visit_call_attr_reader_writer_accessor(node, 'W')
    when :attr_accessor
      _visit_call_attr_reader_writer_accessor(node, 'RW')
    when :include
      _visit_call_include(node)
    when :extend
      _visit_call_extend(node)
    when :public
      super
      _visit_call_public_private_protected(node, :public)
    when :private
      super
      _visit_call_public_private_protected(node, :private)
    when :protected
      super
      _visit_call_public_private_protected(node, :protected)
    when :private_constant
      _visit_call_private_constant(node)
    when :public_constant
      _visit_call_public_constant(node)
    when :require
      _visit_call_require(node)
    when :alias_method
      _visit_call_alias_method(node)
    when :module_function
      super
      _visit_call_module_function(node)
    when :public_class_method
      super
      _visit_call_public_private_class_method(node, :public)
    when :private_class_method
      super
      _visit_call_public_private_class_method(node, :private)
    else
      super
    end
  else
    super
  end
end

#visit_class_node(node) ⇒ Object

# File 'lib/rdoc/parser/ruby.rb', line 1072

def visit_class_node(node)
  node.constant_path.accept(self)
  node.superclass&.accept(self)
  @scanner.process_comments_until(node.location.start_line - 1)
  superclass_name = constant_path_string(node.superclass) if node.superclass
  superclass_expr = node.superclass.slice if node.superclass && !superclass_name
  class_name = constant_path_string(node.constant_path)
  klass = @scanner.add_module_or_class(class_name, node.location.start_line, node.location.end_line, is_class: true, superclass_name: superclass_name, superclass_expr: superclass_expr) if class_name
  if klass
    @scanner.with_container(klass) do
      node.body&.accept(self)
      @scanner.process_comments_until(node.location.end_line)
    end
  else
    @scanner.skip_comments_until(node.location.end_line)
  end
end

#visit_constant_path_write_node(node) ⇒ Object

# File 'lib/rdoc/parser/ruby.rb', line 1187

def visit_constant_path_write_node(node)
  @scanner.process_comments_until(node.location.start_line - 1)
  path = constant_path_string(node.target)
  return unless path

  alias_path = constant_path_string(node.value)
  @scanner.add_constant(
    path,
    alias_path || node.value.slice,
    node.location.start_line,
    node.location.end_line,
    alias_path: alias_path
  )
  @scanner.skip_comments_until(node.location.end_line)
  # Do not traverse rhs not to document `A::B = Struct.new{def undocumentable_method; end}`
end

#visit_constant_write_node(node) ⇒ Object

# File 'lib/rdoc/parser/ruby.rb', line 1204

def visit_constant_write_node(node)
  @scanner.process_comments_until(node.location.start_line - 1)
  alias_path = constant_path_string(node.value)
  @scanner.add_constant(
    node.name.to_s,
    alias_path || node.value.slice,
    node.location.start_line,
    node.location.end_line,
    alias_path: alias_path
  )
  @scanner.skip_comments_until(node.location.end_line)
  # Do not traverse rhs not to document `A = Struct.new{def undocumentable_method; end}`
end

#visit_def_node(node) ⇒ Object

# File 'lib/rdoc/parser/ruby.rb', line 1127

def visit_def_node(node)
  start_line = node.location.start_line
  args_end_line = node.parameters&.location&.end_line || start_line
  end_line = node.location.end_line
  @scanner.process_comments_until(start_line - 1)

  return if @scanner.in_proc_block

  case node.receiver
  when Prism::NilNode, Prism::TrueNode, Prism::FalseNode
    visibility = :public
    singleton = false
    receiver_name =
      case node.receiver
      when Prism::NilNode
        'NilClass'
      when Prism::TrueNode
        'TrueClass'
      when Prism::FalseNode
        'FalseClass'
      end
    receiver_fallback_type = :class
  when Prism::SelfNode
    # singleton method of a singleton class is not documentable
    return if @scanner.singleton
    visibility = :public
    singleton = true
  when Prism::ConstantReadNode, Prism::ConstantPathNode
    visibility = :public
    singleton = true
    receiver_name = constant_path_string(node.receiver)
    receiver_fallback_type = :module
    return unless receiver_name
  when nil
    visibility = @scanner.visibility
    singleton = @scanner.singleton
  else
    # `def (unknown expression).method_name` is not documentable
    return
  end
  name = node.name.to_s
  params, block_params, calls_super = MethodSignatureVisitor.scan_signature(node)
  @scanner.add_method(
    name,
    receiver_name: receiver_name,
    receiver_fallback_type: receiver_fallback_type,
    visibility: visibility,
    singleton: singleton,
    params: params,
    block_params: block_params,
    calls_super: calls_super,
    node_id: node.node_id,
    start_line: start_line,
    args_end_line: args_end_line,
    end_line: end_line
  )
ensure
  @scanner.skip_comments_until(end_line)
end

#visit_if_node(node) ⇒ Object Also known as: visit_unless_node

# File 'lib/rdoc/parser/ruby.rb', line 978

def visit_if_node(node)
  if node.end_keyword
    super
  else
    # Visit with the order in text representation to handle this method comment
    # # comment
    # def f
    # end if call_node
    node.statements.accept(self)
    node.predicate.accept(self)
  end
end

#visit_module_node(node) ⇒ Object

# File 'lib/rdoc/parser/ruby.rb', line 1057

def visit_module_node(node)
  node.constant_path.accept(self)
  @scanner.process_comments_until(node.location.start_line - 1)
  module_name = constant_path_string(node.constant_path)
  mod = @scanner.add_module_or_class(module_name, node.location.start_line, node.location.end_line) if module_name
  if mod
    @scanner.with_container(mod) do
      node.body&.accept(self)
      @scanner.process_comments_until(node.location.end_line)
    end
  else
    @scanner.skip_comments_until(node.location.end_line)
  end
end

#visit_singleton_class_node(node) ⇒ Object

# File 'lib/rdoc/parser/ruby.rb', line 1090

def visit_singleton_class_node(node)
  # A comment linked to the `class << ...` line (e.g. a document control
  # directive) belongs to the enclosing scope, not to the singleton scope
  @scanner.process_comments_until(node.location.start_line)

  if @scanner.has_modifier_nodoc?(node.location.start_line)
    # Skip visiting inside the singleton class. Also skips creation of node.expression as a module
    @scanner.skip_comments_until(node.location.end_line)
    return
  end

  expression = node.expression
  expression = expression.body.body.first if expression.is_a?(Prism::ParenthesesNode) && expression.body&.body&.size == 1

  case expression
  when Prism::ConstantWriteNode
    # Accept `class << (NameErrorCheckers = Object.new)` as a module which is not actually a module
    mod = @scanner.container.add_module(NormalModule, expression.name.to_s)
    mod.ignore if @scanner.document_suppressed? && mod.in_files.empty?
  when Prism::ConstantPathNode, Prism::ConstantReadNode
    expression_name = constant_path_string(expression)
    # If a constant_path does not exist, RDoc creates a module
    mod = @scanner.find_or_create_lexical_module_path(expression_name, :module) if expression_name
  when Prism::SelfNode
    mod = @scanner.container if @scanner.container != @top_level
  end
  expression.accept(self)
  if mod
    @scanner.with_container(mod, singleton: true) do
      node.body&.accept(self)
      @scanner.process_comments_until(node.location.end_line)
    end
  else
    @scanner.skip_comments_until(node.location.end_line)
  end
end