[ruby/prism] Document fewer useless methods/classes

(https://github.com/ruby/prism/pull/3908)

* Add missing nodocs for FFI

When generating docs in ruby/prism, this doesn't seem to matter.

But on docs.ruby-lang.org these take over the actual documentation.

* Nodoc various utility methods

They don't tell much of a story and just pull attention away from actually unique methods

* Nodoc some private functions/modules

* Nodoc translator implementation details

As well as some functionality from ripper that is nodoc in ruby

* Stop documenting visitor implementation details

These result in so many methods that are searchable
and give no actual benefit.
Toplevel docs are all you need to understand the usecase.

https://github.com/ruby/prism/commit/0bd9a7d373

11 files changed, 53 insertions, 60 deletions

diff --git a/lib/prism/ffi.rb b/lib/prism/ffi.rb
index 618324ded6..520c773b43 100644
--- a/lib/prism/ffi.rb
+++ b/lib/prism/ffi.rb
@@ -233,7 +233,7 @@ module Prism
   # 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 @@ module Prism
 
   # 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 5b685716cc..e8d2ce1b19 100644
--- a/lib/prism/lex_compat.rb
+++ b/lib/prism/lex_compat.rb
@@ -20,7 +20,7 @@ module Prism
       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 2498ae7e14..53ca168c0e 100644
--- a/lib/prism/parse_result.rb
+++ b/lib/prism/parse_result.rb
@@ -163,7 +163,7 @@ module Prism
 
     # 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 @@ module Prism
     end
 
     # Returns a string representation of this location.
-    def inspect
+    def inspect # :nodoc:
       "#<Prism::Location @start_offset=#{@start_offset} @length=#{@length} start_line=#{start_line}>"
     end
 
@@ -477,12 +477,12 @@ module Prism
     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 @@ module Prism
     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 @@ module Prism
     end
 
     # Returns a string representation of this comment.
-    def inspect
+    def inspect # :nodoc:
       "#<Prism::InlineComment @location=#{location.inspect}>"
     end
   end
@@ -562,7 +562,7 @@ module Prism
     end
 
     # Returns a string representation of this comment.
-    def inspect
+    def inspect # :nodoc:
       "#<Prism::EmbDocComment @location=#{location.inspect}>"
     end
   end
@@ -592,12 +592,12 @@ module Prism
     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:
       "#<Prism::MagicComment @key=#{key.inspect} @value=#{value.inspect}>"
     end
   end
@@ -626,12 +626,12 @@ module Prism
     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:
       "#<Prism::ParseError @type=#{@type.inspect} @message=#{@message.inspect} @location=#{@location.inspect} @level=#{@level.inspect}>"
     end
   end
@@ -660,12 +660,12 @@ module Prism
     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:
       "#<Prism::ParseWarning @type=#{@type.inspect} @message=#{@message.inspect} @location=#{@location.inspect} @level=#{@level.inspect}>"
     end
   end
@@ -705,7 +705,7 @@ module Prism
     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 @@ module Prism
     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 @@ module Prism
     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 @@ module Prism
     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 @@ module Prism
     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 @@ module Prism
     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 @@ module Prism
     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 6ad2d9e5b9..4a0c5ef54d 100644
--- a/lib/prism/pattern.rb
+++ b/lib/prism/pattern.rb
@@ -100,23 +100,23 @@ module Prism
 
     # 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 @@ module Prism
     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 @@ module Prism
 
     # 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 @@ module Prism
 
     # 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 @@ module Prism
     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 @@ module Prism
 
     # in ""
     # in "foo"
-    def compile_string_node(node)
+    def compile_string_node(node) # :nodoc:
       string = node.unescaped
 
       ->(attribute) { string === attribute }
@@ -233,7 +233,7 @@ module Prism
 
     # 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 @@ module Prism
 
     # 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 fed4ac4cd1..70031f133a 100644
--- a/lib/prism/translation/parser.rb
+++ b/lib/prism/translation/parser.rb
@@ -33,7 +33,7 @@ module Prism
       # 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 bd3618b162..37951a1d40 100644
--- a/lib/prism/translation/parser/compiler.rb
+++ b/lib/prism/translation/parser/compiler.rb
@@ -6,9 +6,9 @@ module Prism
     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 0491e79cd2..8e18a3cd1e 100644
--- a/lib/prism/translation/parser/lexer.rb
+++ b/lib/prism/translation/parser/lexer.rb
@@ -10,7 +10,7 @@ module Prism
     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 @@ module Prism
         # 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 @@ module Prism
           @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 5b2aa37833..2a3eaa4001 100644
--- a/lib/prism/translation/ripper.rb
+++ b/lib/prism/translation/ripper.rb
@@ -594,6 +594,8 @@ module Prism
       # Visitor methods
       ##########################################################################
 
+      # :stopdoc:
+
       # alias foo bar
       # ^^^^^^^^^^^^^
       def visit_alias_method_node(node)
@@ -3458,6 +3460,8 @@ module Prism
         @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 cbcdcd47cc..c6aeae4bd7 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 @@ module Prism
           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 @@ module Prism
         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 8cfefc8472..46c0333544 100644
--- a/lib/prism/translation/ripper/sexp.rb
+++ b/lib/prism/translation/ripper/sexp.rb
@@ -8,9 +8,7 @@ module Prism
     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 @@ module Prism
         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 @@ module Prism
             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 c026c4ad9c..5f4a8cab92 100644
--- a/lib/prism/translation/ruby_parser.rb
+++ b/lib/prism/translation/ruby_parser.rb
@@ -19,7 +19,7 @@ module Prism
     # 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.