[ruby/prism] More Ruby docs

https://github.com/ruby/prism/commit/ca9a660f52

4 files changed, 25 insertions, 5 deletions

diff --git a/prism/templates/lib/prism/dispatcher.rb.erb b/prism/templates/lib/prism/dispatcher.rb.erb
index 3fe9d75bcc..1370ca7636 100644
--- a/prism/templates/lib/prism/dispatcher.rb.erb
+++ b/prism/templates/lib/prism/dispatcher.rb.erb
@@ -34,23 +34,24 @@ module Prism
     # attr_reader listeners: Hash[Symbol, Array[Listener]]
     attr_reader :listeners
 
+    # Initialize a new dispatcher.
     def initialize
       @listeners = {}
     end
 
-    # Register a listener for one or more events
+    # Register a listener for one or more events.
     #
     # def register: (Listener, *Symbol) -> void
     def register(listener, *events)
       events.each { |event| (listeners[event] ||= []) << listener }
     end
 
-    # Walks `root` dispatching events to all registered listeners
+    # Walks `root` dispatching events to all registered listeners.
     #
     # def dispatch: (Node) -> void
     alias dispatch visit
 
-    # Dispatches a single event for `node` to all registered listeners
+    # Dispatches a single event for `node` to all registered listeners.
     #
     # def dispatch_once: (Node) -> void
     def dispatch_once(node)
@@ -67,7 +68,7 @@ module Prism
     end
     <%- end -%>
 
-    class DispatchOnce < Visitor
+    class DispatchOnce < Visitor # :nodoc:
       attr_reader :listeners
 
       def initialize(listeners)
diff --git a/prism/templates/lib/prism/node.rb.erb b/prism/templates/lib/prism/node.rb.erb
index a97ae557d5..e41383a79b 100644
--- a/prism/templates/lib/prism/node.rb.erb
+++ b/prism/templates/lib/prism/node.rb.erb
@@ -2,6 +2,8 @@ module Prism
   # This represents a node in the tree. It is the parent class of all of the
   # various node types.
   class Node
+    # A Location instance that represents the location of this node in the
+    # source.
     attr_reader :location
 
     def newline? # :nodoc:
diff --git a/prism/templates/lib/prism/serialize.rb.erb b/prism/templates/lib/prism/serialize.rb.erb
index da507709e3..a8a6a2dd47 100644
--- a/prism/templates/lib/prism/serialize.rb.erb
+++ b/prism/templates/lib/prism/serialize.rb.erb
@@ -12,11 +12,21 @@ if String.instance_method(:unpack1).parameters.none? { |_, name| name == :offset
 end
 
 module Prism
+  # A module responsible for deserializing parse results.
   module Serialize
+    # The major version of prism that we are expecting to find in the serialized
+    # strings.
     MAJOR_VERSION = 0
+
+    # The minor version of prism that we are expecting to find in the serialized
+    # strings.
     MINOR_VERSION = 16
+
+    # The patch version of prism that we are expecting to find in the serialized
+    # strings.
     PATCH_VERSION = 0
 
+    # Deserialize the AST represented by the given string into a parse result.
     def self.load(input, serialized)
       input = input.dup
       source = Source.new(input)
@@ -27,11 +37,13 @@ module Prism
       result
     end
 
+    # Deserialize the tokens represented by the given string into a parse
+    # result.
     def self.load_tokens(source, serialized)
       Loader.new(source, serialized).load_tokens_result
     end
 
-    class Loader
+    class Loader # :nodoc:
       attr_reader :encoding, :input, :serialized, :io
       attr_reader :constant_pool_offset, :constant_pool, :source
 
@@ -272,6 +284,7 @@ module Prism
       end
     end
 
+    # The token types that can be indexed by their enum values.
     TOKEN_TYPES = [
       nil,
       <%- tokens.each do |token| -%>
diff --git a/prism/templates/lib/prism/visitor.rb.erb b/prism/templates/lib/prism/visitor.rb.erb
index 1c33e7a092..04156cc7a9 100644
--- a/prism/templates/lib/prism/visitor.rb.erb
+++ b/prism/templates/lib/prism/visitor.rb.erb
@@ -4,14 +4,18 @@ module Prism
   # implement each one that they need. For a default implementation that
   # continues walking the tree, see the Visitor class.
   class BasicVisitor
+    # Calls `accept` on the given node if it is not `nil`, which in turn should
+    # call back into this visitor by calling the appropriate `visit_*` method.
     def visit(node)
       node&.accept(self)
     end
 
+    # Visits each node in `nodes` by calling `accept` on each one.
     def visit_all(nodes)
       nodes.each { |node| node&.accept(self) }
     end
 
+    # Visits the child nodes of `node` by calling `accept` on each one.
     def visit_child_nodes(node)
       node.compact_child_nodes.each { |node| node.accept(self) }
     end