diff --git a/lib/prism/ffi.rb b/lib/prism/ffi.rb index 618324ded6efa0..520c773b43a408 100644 --- a/lib/prism/ffi.rb +++ b/lib/prism/ffi.rb @@ -233,7 +233,7 @@ def self.with_file(filepath) # The version constant is set by reading the result of calling pm_version. VERSION = LibRubyParser.pm_version.read_string.freeze - class << self + class << self # :nodoc: # Mirror the Prism.dump API by using the serialization API. def dump(source, **options) LibRubyParser::PrismString.with_string(source) { |string| dump_common(string, options) } @@ -554,7 +554,7 @@ def dump_options(options) # Here we are going to patch StringQuery to put in the class-level methods so # that it can maintain a consistent interface - class StringQuery + class StringQuery # :nodoc: class << self # Mirrors the C extension's StringQuery::local? method. def local?(string) diff --git a/lib/prism/lex_compat.rb b/lib/prism/lex_compat.rb index 5b685716cc5569..e8d2ce1b192ceb 100644 --- a/lib/prism/lex_compat.rb +++ b/lib/prism/lex_compat.rb @@ -20,7 +20,7 @@ def initialize(value, comments, magic_comments, data_loc, errors, warnings, sour end # Implement the hash pattern matching interface for Result. - def deconstruct_keys(keys) + def deconstruct_keys(keys) # :nodoc: super.merge!(value: value) end end diff --git a/lib/prism/parse_result.rb b/lib/prism/parse_result.rb index 2498ae7e145fed..53ca168c0e81a1 100644 --- a/lib/prism/parse_result.rb +++ b/lib/prism/parse_result.rb @@ -163,7 +163,7 @@ def deep_freeze # Binary search through the offsets to find the line number for the given # byte offset. - def find_line(byte_offset) + def find_line(byte_offset) # :nodoc: index = offsets.bsearch_index { |offset| offset > byte_offset } || offsets.length index - 1 end @@ -350,7 +350,7 @@ def chop end # Returns a string representation of this location. - def inspect + def inspect # :nodoc: "#" end @@ -477,12 +477,12 @@ def cached_end_code_units_column(cache) end # Implement the hash pattern matching interface for Location. - def deconstruct_keys(keys) + def deconstruct_keys(keys) # :nodoc: { start_offset: start_offset, end_offset: end_offset } end # Implement the pretty print interface for Location. - def pretty_print(q) + def pretty_print(q) # :nodoc: q.text("(#{start_line},#{start_column})-(#{end_line},#{end_column})") end @@ -528,7 +528,7 @@ def initialize(location) end # Implement the hash pattern matching interface for Comment. - def deconstruct_keys(keys) + def deconstruct_keys(keys) # :nodoc: { location: location } end @@ -548,7 +548,7 @@ def trailing? end # Returns a string representation of this comment. - def inspect + def inspect # :nodoc: "#" end end @@ -562,7 +562,7 @@ def trailing? end # Returns a string representation of this comment. - def inspect + def inspect # :nodoc: "#" end end @@ -592,12 +592,12 @@ def value end # Implement the hash pattern matching interface for MagicComment. - def deconstruct_keys(keys) + def deconstruct_keys(keys) # :nodoc: { key_loc: key_loc, value_loc: value_loc } end # Returns a string representation of this magic comment. - def inspect + def inspect # :nodoc: "#" end end @@ -626,12 +626,12 @@ def initialize(type, message, location, level) end # Implement the hash pattern matching interface for ParseError. - def deconstruct_keys(keys) + def deconstruct_keys(keys) # :nodoc: { type: type, message: message, location: location, level: level } end # Returns a string representation of this error. - def inspect + def inspect # :nodoc: "#" end end @@ -660,12 +660,12 @@ def initialize(type, message, location, level) end # Implement the hash pattern matching interface for ParseWarning. - def deconstruct_keys(keys) + def deconstruct_keys(keys) # :nodoc: { type: type, message: message, location: location, level: level } end # Returns a string representation of this warning. - def inspect + def inspect # :nodoc: "#" end end @@ -705,7 +705,7 @@ def initialize(comments, magic_comments, data_loc, errors, warnings, source) end # Implement the hash pattern matching interface for Result. - def deconstruct_keys(keys) + def deconstruct_keys(keys) # :nodoc: { comments: comments, magic_comments: magic_comments, data_loc: data_loc, errors: errors, warnings: warnings } end @@ -752,7 +752,7 @@ def initialize(value, comments, magic_comments, data_loc, errors, warnings, sour end # Implement the hash pattern matching interface for ParseResult. - def deconstruct_keys(keys) + def deconstruct_keys(keys) # :nodoc: super.merge!(value: value) end @@ -786,7 +786,7 @@ def initialize(value, comments, magic_comments, data_loc, errors, warnings, sour end # Implement the hash pattern matching interface for LexResult. - def deconstruct_keys(keys) + def deconstruct_keys(keys) # :nodoc: super.merge!(value: value) end end @@ -804,7 +804,7 @@ def initialize(value, comments, magic_comments, data_loc, errors, warnings, sour end # Implement the hash pattern matching interface for ParseLexResult. - def deconstruct_keys(keys) + def deconstruct_keys(keys) # :nodoc: super.merge!(value: value) end end @@ -830,7 +830,7 @@ def initialize(source, type, value, location) end # Implement the hash pattern matching interface for Token. - def deconstruct_keys(keys) + def deconstruct_keys(keys) # :nodoc: { type: type, value: value, location: location } end @@ -842,7 +842,7 @@ def location end # Implement the pretty print interface for Token. - def pretty_print(q) + def pretty_print(q) # :nodoc: q.group do q.text(type.to_s) self.location.pretty_print(q) @@ -864,7 +864,7 @@ def ==(other) end # Returns a string representation of this token. - def inspect + def inspect # :nodoc: location super end diff --git a/lib/prism/pattern.rb b/lib/prism/pattern.rb index 6ad2d9e5b9566f..4a0c5ef54de46a 100644 --- a/lib/prism/pattern.rb +++ b/lib/prism/pattern.rb @@ -100,23 +100,23 @@ def scan(root) # Shortcut for combining two procs into one that returns true if both return # true. - def combine_and(left, right) + def combine_and(left, right) # :nodoc: ->(other) { left.call(other) && right.call(other) } end # Shortcut for combining two procs into one that returns true if either # returns true. - def combine_or(left, right) + def combine_or(left, right) # :nodoc: ->(other) { left.call(other) || right.call(other) } end # Raise an error because the given node is not supported. - def compile_error(node) + def compile_error(node) # :nodoc: raise CompilationError, node.inspect end # in [foo, bar, baz] - def compile_array_pattern_node(node) + def compile_array_pattern_node(node) # :nodoc: compile_error(node) if !node.rest.nil? || node.posts.any? constant = node.constant @@ -141,12 +141,12 @@ def compile_array_pattern_node(node) end # in foo | bar - def compile_alternation_pattern_node(node) + def compile_alternation_pattern_node(node) # :nodoc: combine_or(compile_node(node.left), compile_node(node.right)) end # in Prism::ConstantReadNode - def compile_constant_path_node(node) + def compile_constant_path_node(node) # :nodoc: parent = node.parent if parent.is_a?(ConstantReadNode) && parent.slice == "Prism" @@ -161,12 +161,12 @@ def compile_constant_path_node(node) # in ConstantReadNode # in String - def compile_constant_read_node(node) + def compile_constant_read_node(node) # :nodoc: compile_constant_name(node, node.name) end # Compile a name associated with a constant. - def compile_constant_name(node, name) + def compile_constant_name(node, name) # :nodoc: if Prism.const_defined?(name, false) clazz = Prism.const_get(name) @@ -182,7 +182,7 @@ def compile_constant_name(node, name) # in InstanceVariableReadNode[name: Symbol] # in { name: Symbol } - def compile_hash_pattern_node(node) + def compile_hash_pattern_node(node) # :nodoc: compile_error(node) if node.rest compiled_constant = compile_node(node.constant) if node.constant @@ -212,12 +212,12 @@ def compile_hash_pattern_node(node) end # in nil - def compile_nil_node(node) + def compile_nil_node(node) # :nodoc: ->(attribute) { attribute.nil? } end # in /foo/ - def compile_regular_expression_node(node) + def compile_regular_expression_node(node) # :nodoc: regexp = Regexp.new(node.unescaped, node.closing[1..]) ->(attribute) { regexp === attribute } @@ -225,7 +225,7 @@ def compile_regular_expression_node(node) # in "" # in "foo" - def compile_string_node(node) + def compile_string_node(node) # :nodoc: string = node.unescaped ->(attribute) { string === attribute } @@ -233,7 +233,7 @@ def compile_string_node(node) # in :+ # in :foo - def compile_symbol_node(node) + def compile_symbol_node(node) # :nodoc: symbol = node.unescaped.to_sym ->(attribute) { symbol === attribute } @@ -241,7 +241,7 @@ def compile_symbol_node(node) # Compile any kind of node. Dispatch out to the individual compilation # methods based on the type of node. - def compile_node(node) + def compile_node(node) # :nodoc: case node when AlternationPatternNode compile_alternation_pattern_node(node) diff --git a/lib/prism/translation/parser.rb b/lib/prism/translation/parser.rb index fed4ac4cd1f0fd..70031f133a1e5e 100644 --- a/lib/prism/translation/parser.rb +++ b/lib/prism/translation/parser.rb @@ -33,7 +33,7 @@ class Parser < ::Parser::Base # The parser gem has a list of diagnostics with a hard-coded set of error # messages. We create our own diagnostic class in order to set our own # error messages. - class PrismDiagnostic < Diagnostic + class PrismDiagnostic < Diagnostic # :nodoc: # This is the cached message coming from prism. attr_reader :message diff --git a/lib/prism/translation/parser/compiler.rb b/lib/prism/translation/parser/compiler.rb index bd3618b16289e7..37951a1d400159 100644 --- a/lib/prism/translation/parser/compiler.rb +++ b/lib/prism/translation/parser/compiler.rb @@ -6,9 +6,9 @@ module Translation class Parser # A visitor that knows how to convert a prism syntax tree into the # whitequark/parser gem's syntax tree. - class Compiler < ::Prism::Compiler + class Compiler < ::Prism::Compiler # :nodoc: # Raised when the tree is malformed or there is a bug in the compiler. - class CompilationError < StandardError + class CompilationError < StandardError # :nodoc: end # The Parser::Base instance that is being used to build the AST. diff --git a/lib/prism/translation/parser/lexer.rb b/lib/prism/translation/parser/lexer.rb index 0491e79cd212e6..8e18a3cd1e6454 100644 --- a/lib/prism/translation/parser/lexer.rb +++ b/lib/prism/translation/parser/lexer.rb @@ -10,7 +10,7 @@ module Translation class Parser # Accepts a list of prism tokens and converts them into the expected # format for the parser gem. - class Lexer + class Lexer # :nodoc: # These tokens are always skipped TYPES_ALWAYS_SKIP = Set.new(%i[IGNORED_NEWLINE __END__ EOF]) private_constant :TYPES_ALWAYS_SKIP @@ -188,8 +188,8 @@ class Lexer # without them. We should find another way to do this, but in the # meantime we'll hide them from the documentation and mark them as # private constants. - EXPR_BEG = 0x1 # :nodoc: - EXPR_LABEL = 0x400 # :nodoc: + EXPR_BEG = 0x1 + EXPR_LABEL = 0x400 # It is used to determine whether `do` is of the token type `kDO` or `kDO_LAMBDA`. # @@ -232,7 +232,7 @@ def initialize(source_buffer, lexed, offset_cache) @offset_cache = offset_cache end - Range = ::Parser::Source::Range # :nodoc: + Range = ::Parser::Source::Range private_constant :Range # Convert the prism tokens into the expected format for the parser gem. diff --git a/lib/prism/translation/ripper.rb b/lib/prism/translation/ripper.rb index 5b2aa37833207e..2a3eaa4001adc8 100644 --- a/lib/prism/translation/ripper.rb +++ b/lib/prism/translation/ripper.rb @@ -594,6 +594,8 @@ def parse # Visitor methods ########################################################################## + # :stopdoc: + # alias foo bar # ^^^^^^^^^^^^^ def visit_alias_method_node(node) @@ -3458,6 +3460,8 @@ def bounds(location) @column = location.start_column end + # :startdoc: + ########################################################################## # Ripper interface ########################################################################## diff --git a/lib/prism/translation/ripper/lexer.rb b/lib/prism/translation/ripper/lexer.rb index cbcdcd47cc3af0..c6aeae4bd78695 100644 --- a/lib/prism/translation/ripper/lexer.rb +++ b/lib/prism/translation/ripper/lexer.rb @@ -7,8 +7,7 @@ module Prism module Translation class Ripper class Lexer < Ripper # :nodoc: - # :stopdoc: - class State + class State # :nodoc: attr_reader :to_int, :to_s def initialize(i) @@ -48,7 +47,7 @@ def self.[](i) end end - class Elem + class Elem # :nodoc: attr_accessor :pos, :event, :tok, :state, :message def initialize(pos, event, tok, state, message = nil) @@ -128,8 +127,6 @@ def parse(...) def scan(...) parse(...) end - - # :startdoc: end end end diff --git a/lib/prism/translation/ripper/sexp.rb b/lib/prism/translation/ripper/sexp.rb index 8cfefc84723b29..46c03335445511 100644 --- a/lib/prism/translation/ripper/sexp.rb +++ b/lib/prism/translation/ripper/sexp.rb @@ -8,9 +8,7 @@ module Translation class Ripper # This class mirrors the ::Ripper::SexpBuilder subclass of ::Ripper that # returns the arrays of [type, *children]. - class SexpBuilder < Ripper - # :stopdoc: - + class SexpBuilder < Ripper # :nodoc: attr_reader :error private @@ -65,16 +63,12 @@ def on_error(mesg) remove_method :on_parse_error alias on_parse_error on_error alias compile_error on_error - - # :startdoc: end # This class mirrors the ::Ripper::SexpBuilderPP subclass of ::Ripper that # returns the same values as ::Ripper::SexpBuilder except with a couple of # niceties that flatten linked lists into arrays. - class SexpBuilderPP < SexpBuilder - # :stopdoc: - + class SexpBuilderPP < SexpBuilder # :nodoc: private def on_heredoc_dedent(val, width) @@ -118,8 +112,6 @@ def on_mlhs_add_post(list, post) alias_method "on_#{event}", :_dispatch_event_push end end - - # :startdoc: end end end diff --git a/lib/prism/translation/ruby_parser.rb b/lib/prism/translation/ruby_parser.rb index c026c4ad9c57af..5f4a8cab9268cf 100644 --- a/lib/prism/translation/ruby_parser.rb +++ b/lib/prism/translation/ruby_parser.rb @@ -19,7 +19,7 @@ module Translation # seattlerb/ruby_parser gem's syntax tree. class RubyParser # A prism visitor that builds Sexp objects. - class Compiler < ::Prism::Compiler + class Compiler < ::Prism::Compiler # :nodoc: # This is the name of the file that we are compiling. We set it on every # Sexp object that is generated, and also use it to compile `__FILE__` # nodes. diff --git a/prism/templates/lib/prism/compiler.rb.erb b/prism/templates/lib/prism/compiler.rb.erb index 66dbe666b90934..031557a221de3c 100644 --- a/prism/templates/lib/prism/compiler.rb.erb +++ b/prism/templates/lib/prism/compiler.rb.erb @@ -18,24 +18,23 @@ module Prism # class Compiler < Visitor # Visit an individual node. - def visit(node) + def visit(node) # :nodoc: node&.accept(self) end # Visit a list of nodes. - def visit_all(nodes) + def visit_all(nodes) # :nodoc: nodes.map { |node| node&.accept(self) } end # Visit the child nodes of the given node. - def visit_child_nodes(node) + def visit_child_nodes(node) # :nodoc: node.each_child_node.map { |node| node.accept(self) } end <%- nodes.each_with_index do |node, index| -%> <%= "\n" if index != 0 -%> - # Compile a <%= node.name %> node - def visit_<%= node.human %>(node) + def visit_<%= node.human %>(node) # :nodoc: node.each_child_node.map { |node| node.accept(self) } end <%- end -%> diff --git a/prism/templates/lib/prism/dispatcher.rb.erb b/prism/templates/lib/prism/dispatcher.rb.erb index 52478451c99b9d..16ce421cc5d093 100644 --- a/prism/templates/lib/prism/dispatcher.rb.erb +++ b/prism/templates/lib/prism/dispatcher.rb.erb @@ -56,7 +56,7 @@ module Prism end # Register a listener for the given events. - private def register_events(listener, events) + private def register_events(listener, events) # :nodoc: events.each { |event| (listeners[event] ||= []) << listener } end @@ -73,9 +73,7 @@ module Prism end <%- nodes.each do |node| -%> - # Dispatch enter and leave events for <%= node.name %> nodes and continue - # walking the tree. - def visit_<%= node.human %>(node) + def visit_<%= node.human %>(node) # :nodoc: listeners[:on_<%= node.human %>_enter]&.each { |listener| listener.on_<%= node.human %>_enter(node) } super listeners[:on_<%= node.human %>_leave]&.each { |listener| listener.on_<%= node.human %>_leave(node) } diff --git a/prism/templates/lib/prism/dot_visitor.rb.erb b/prism/templates/lib/prism/dot_visitor.rb.erb index 87de1965b083b0..13c53af0d430d8 100644 --- a/prism/templates/lib/prism/dot_visitor.rb.erb +++ b/prism/templates/lib/prism/dot_visitor.rb.erb @@ -106,8 +106,7 @@ module Prism end <%- nodes.each do |node| -%> - # Visit a <%= node.name %> node. - def visit_<%= node.human %>(node) + def visit_<%= node.human %>(node) # :nodoc: table = Table.new("<%= node.name %>") id = node_id(node) <%- if (node_flags = node.flags) -%> @@ -165,19 +164,19 @@ module Prism private # Generate a unique node ID for a node throughout the digraph. - def node_id(node) + def node_id(node) # :nodoc: "Node_#{node.object_id}" end # Inspect a location to display the start and end line and columns in bytes. - def location_inspect(location) + def location_inspect(location) # :nodoc: "(#{location.start_line},#{location.start_column})-(#{location.end_line},#{location.end_column})" end <%- flags.each do |flag| -%> # Inspect a node that has <%= flag.human %> flags to display the flags as a # comma-separated list. - def <%= flag.human %>_inspect(node) + def <%= flag.human %>_inspect(node) # :nodoc: flags = [] #: Array[String] <%- flag.values.each do |value| -%> flags << "<%= value.name.downcase %>" if node.<%= value.name.downcase %>? diff --git a/prism/templates/lib/prism/inspect_visitor.rb.erb b/prism/templates/lib/prism/inspect_visitor.rb.erb index 3cfe615d850934..9a33cb8110f076 100644 --- a/prism/templates/lib/prism/inspect_visitor.rb.erb +++ b/prism/templates/lib/prism/inspect_visitor.rb.erb @@ -17,14 +17,13 @@ module Prism private_constant :Replace # The current prefix string. - attr_reader :indent + attr_reader :indent # :nodoc: # The list of commands that we need to execute in order to compose the # final string. - attr_reader :commands + attr_reader :commands # :nodoc: - # Initializes a new instance of the InspectVisitor. - def initialize(indent = +"") + def initialize(indent = +"") # :nodoc: @indent = indent @commands = [] end @@ -37,7 +36,7 @@ module Prism end # Compose the final string. - def compose + def compose # :nodoc: buffer = +"" replace = nil @@ -66,8 +65,7 @@ module Prism end <%- nodes.each do |node| -%> - # Inspect a <%= node.name %> node. - def visit_<%= node.human %>(node) + def visit_<%= node.human %>(node) # :nodoc: commands << [inspect_node(<%= node.name.inspect %>, node), indent] <%- (fields = [node.flags || Prism::Template::Flags.empty, *node.fields]).each_with_index do |field, index| -%> <%- pointer = index == fields.length - 1 ? "└── " : "├── " -%> @@ -114,13 +112,13 @@ module Prism private # Compose a header for the given node. - def inspect_node(name, node) + def inspect_node(name, node) # :nodoc: location = node.location "@ #{name} (location: (#{location.start_line},#{location.start_column})-(#{location.end_line},#{location.end_column}))\n" end # Compose a string representing the given inner location field. - def inspect_location(location) + def inspect_location(location) # :nodoc: if location "(#{location.start_line},#{location.start_column})-(#{location.end_line},#{location.end_column}) = #{location.slice.inspect}" else diff --git a/prism/templates/lib/prism/mutation_compiler.rb.erb b/prism/templates/lib/prism/mutation_compiler.rb.erb index 565ee4e315d47d..b223860f2f6ff2 100644 --- a/prism/templates/lib/prism/mutation_compiler.rb.erb +++ b/prism/templates/lib/prism/mutation_compiler.rb.erb @@ -5,8 +5,7 @@ module Prism class MutationCompiler < Compiler <%- nodes.each_with_index do |node, index| -%> <%= "\n" if index != 0 -%> - # Copy a <%= node.name %> node - def visit_<%= node.human %>(node) + def visit_<%= node.human %>(node) # :nodoc: <%- fields = node.fields.select { |field| [Prism::Template::NodeField, Prism::Template::OptionalNodeField, Prism::Template::NodeListField].include?(field.class) } -%> <%- if fields.any? -%> node.copy(<%= fields.map { |field| "#{field.name}: #{field.is_a?(Prism::Template::NodeListField) ? "visit_all" : "visit"}(node.#{field.name})" }.join(", ") %>) diff --git a/prism/templates/lib/prism/node.rb.erb b/prism/templates/lib/prism/node.rb.erb index d14a06961a577d..e2f8c0e53c0a17 100644 --- a/prism/templates/lib/prism/node.rb.erb +++ b/prism/templates/lib/prism/node.rb.erb @@ -161,7 +161,7 @@ module Prism # Similar to inspect, but respects the current level of indentation given by # the pretty print object. - def pretty_print(q) + def pretty_print(q) # :nodoc: q.seplist(inspect.chomp.each_line, -> { q.breakable }) do |line| q.text(line.chomp) end @@ -409,8 +409,7 @@ module Prism # def deconstruct: () -> Array[Node?] alias deconstruct child_nodes - # def deconstruct_keys: (Array[Symbol] keys) -> { <%= (["node_id: Integer", "location: Location"] + node.fields.map { |field| "#{field.name}: #{field.rbs_class}" }).join(", ") %> } - def deconstruct_keys(keys) + def deconstruct_keys(keys) # :nodoc: { <%= (["node_id: node_id", "location: location"] + node.fields.map { |field| "#{field.name}: #{field.name}" }).join(", ") %> } end <%- if (node_flags = node.flags) -%> @@ -487,8 +486,7 @@ module Prism <%- end -%> <%- end -%> - # def inspect -> String - def inspect + def inspect # :nodoc: InspectVisitor.compose(self) end diff --git a/prism/templates/lib/prism/serialize.rb.erb b/prism/templates/lib/prism/serialize.rb.erb index 2275d685ca7942..63ef07cb6e9dbd 100644 --- a/prism/templates/lib/prism/serialize.rb.erb +++ b/prism/templates/lib/prism/serialize.rb.erb @@ -3,7 +3,7 @@ require_relative "polyfill/unpack1" module Prism # A module responsible for deserializing parse results. - module Serialize + module Serialize # :nodoc: # The major version of prism that we are expecting to find in the serialized # strings. MAJOR_VERSION = 1