From f12617ec9832ff8979cd86eb717fa9ee5820123e Mon Sep 17 00:00:00 2001
From: Kevin Newton <kddnewton@gmail.com>
Date: Mon, 30 Oct 2023 13:49:32 -0400
Subject: [PATCH] [ruby/prism] Fix up Prism and Debug docs

https://github.com/ruby/prism/commit/c2b7724d91
---
 lib/prism.rb       | 16 ++++++++++++++++
 lib/prism/debug.rb | 26 +++++++++++++++++++++++++-
 2 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/lib/prism.rb b/lib/prism.rb
index b45098480a..86cdadcdad 100644
--- a/lib/prism.rb
+++ b/lib/prism.rb
@@ -1,10 +1,16 @@
 # frozen_string_literal: true
 
+# The Prism Ruby parser.
+#
+# "Parsing Ruby is suddenly manageable!"
+#   - You, hopefully
+#
 module Prism
   # There are many files in prism that are templated to handle every node type,
   # which means the files can end up being quite large. We autoload them to make
   # our require speed faster since consuming libraries are unlikely to use all
   # of these features.
+
   autoload :BasicVisitor, "prism/visitor"
   autoload :Compiler, "prism/compiler"
   autoload :Debug, "prism/debug"
@@ -23,10 +29,14 @@ module Prism
 
   # Some of these constants are not meant to be exposed, so marking them as
   # private here.
+
   private_constant :Debug
   private_constant :LexCompat
   private_constant :LexRipper
 
+  # :call-seq:
+  #   Prism::lex_compat(source, filepath = "") -> Array
+  #
   # Returns an array of tokens that closely resembles that of the Ripper lexer.
   # The only difference is that since we don't keep track of lexer state in the
   # same way, it's going to always return the NONE state.
@@ -34,6 +44,9 @@ module Prism
     LexCompat.new(source, filepath).result
   end
 
+  # :call-seq:
+  #   Prism::lex_ripper(source) -> Array
+  #
   # This lexes with the Ripper lex. It drops any space events but otherwise
   # returns the same tokens. Raises SyntaxError if the syntax in source is
   # invalid.
@@ -41,6 +54,9 @@ module Prism
     LexRipper.new(source).result
   end
 
+  # :call-seq:
+  #   Prism::load(source, serialized) -> ParseResult
+  #
   # Load the serialized AST using the source as a reference into a tree.
   def self.load(source, serialized)
     Serialize.load(source, serialized)
diff --git a/lib/prism/debug.rb b/lib/prism/debug.rb
index bd2eb0842b..f573d0958d 100644
--- a/lib/prism/debug.rb
+++ b/lib/prism/debug.rb
@@ -4,7 +4,9 @@ module Prism
   # This module is used for testing and debugging and is not meant to be used by
   # consumers of this library.
   module Debug
-    class ISeq
+    # A wrapper around a RubyVM::InstructionSequence that provides a more
+    # convenient interface for accessing parts of the iseq.
+    class ISeq # :nodoc:
       attr_reader :parts
 
       def initialize(parts)
@@ -42,6 +44,11 @@ module Prism
       end
     end
 
+    private_constant :ISeq
+
+    # :call-seq:
+    #   Debug::cruby_locals(source) -> Array
+    #
     # For the given source, compiles with CRuby and returns a list of all of the
     # sets of local variables that were encountered.
     def self.cruby_locals(source)
@@ -76,8 +83,16 @@ module Prism
       end
     end
 
+    # Used to hold the place of a local that will be in the local table but
+    # cannot be accessed directly from the source code. For example, the
+    # iteration variable in a for loop or the positional parameter on a method
+    # definition that is destructured.
     AnonymousLocal = Object.new
+    private_constant :AnonymousLocal
 
+    # :call-seq:
+    #   Debug::prism_locals(source) -> Array
+    #
     # For the given source, parses with prism and returns a list of all of the
     # sets of local variables that were encountered.
     def self.prism_locals(source)
@@ -164,10 +179,19 @@ module Prism
       locals
     end
 
+    # :call-seq:
+    #   Debug::newlines(source) -> Array
+    #
+    # For the given source string, return the byte offsets of every newline in
+    # the source.
     def self.newlines(source)
       Prism.parse(source).source.offsets
     end
 
+    # :call-seq:
+    #   Debug::parse_serialize_file(filepath) -> dumped
+    #
+    # For the given file, parse the AST and dump it to a string.
     def self.parse_serialize_file(filepath)
       parse_serialize_file_metadata(filepath, [filepath.bytesize, filepath.b, 0].pack("LA*L"))
     end