From dfdcc98a3c0c7fb323748d1d384601bce6145a5b Mon Sep 17 00:00:00 2001
From: Kevin Newton <kddnewton@gmail.com>
Date: Mon, 30 Oct 2023 15:11:24 -0400
Subject: [PATCH] Finish Ruby documentation

---
 ext/prism/api_pack.c | 29 ++++++++++++++++++++---------
 lib/prism/pack.rb    | 42 +++++++++++++++++++++++++++++++++++++++---
 2 files changed, 59 insertions(+), 12 deletions(-)

diff --git a/ext/prism/api_pack.c b/ext/prism/api_pack.c
index bb2f4ea2153..c746a59634b 100644
--- a/ext/prism/api_pack.c
+++ b/ext/prism/api_pack.c
@@ -164,6 +164,12 @@ pack_encoding_to_ruby(pm_pack_encoding encoding) {
     return rb_enc_from_encoding(rb_enc_from_index(index));
 }
 
+/**
+ * call-seq:
+ *   Pack::parse(version, variant, source) -> Format
+ *  
+ * Parse the given source and return a format object.
+ */
 static VALUE
 pack_parse(VALUE self, VALUE version_symbol, VALUE variant_symbol, VALUE format_string) {
     if (version_symbol != v3_2_0_symbol) {
@@ -223,15 +229,17 @@ pack_parse(VALUE self, VALUE version_symbol, VALUE variant_symbol, VALUE format_
             break;
         }
 
-        VALUE directive_args[9] = { version_symbol,
-                                    variant_symbol,
-                                    rb_usascii_str_new(directive_start, directive_end - directive_start),
-                                    pack_type_to_symbol(type),
-                                    pack_signed_to_symbol(signed_type),
-                                    pack_endian_to_symbol(endian),
-                                    pack_size_to_symbol(size),
-                                    pack_length_type_to_symbol(length_type),
-                                    UINT64T2NUM(length) };
+        VALUE directive_args[9] = {
+            version_symbol,
+            variant_symbol,
+            rb_usascii_str_new(directive_start, directive_end - directive_start),
+            pack_type_to_symbol(type),
+            pack_signed_to_symbol(signed_type),
+            pack_endian_to_symbol(endian),
+            pack_size_to_symbol(size),
+            pack_length_type_to_symbol(length_type),
+            UINT64T2NUM(length)
+        };
 
         rb_ary_push(directives_array, rb_class_new_instance(9, directive_args, rb_cPrismPackDirective));
     }
@@ -242,6 +250,9 @@ pack_parse(VALUE self, VALUE version_symbol, VALUE variant_symbol, VALUE format_
     return rb_class_new_instance(2, format_args, rb_cPrismPackFormat);
 }
 
+/**
+ * The function that gets called when Ruby initializes the prism extension.
+ */
 void
 Init_prism_pack(void) {
     rb_cPrism = rb_define_module("Prism");
diff --git a/lib/prism/pack.rb b/lib/prism/pack.rb
index 1b63d02f24e..00caf553c60 100644
--- a/lib/prism/pack.rb
+++ b/lib/prism/pack.rb
@@ -57,8 +57,34 @@ module Pack
 
     # A directive in the pack template language.
     class Directive
-      attr_reader :version, :variant, :source, :type, :signed, :endian, :size, :length_type, :length
+      # A symbol representing the version of Ruby.
+      attr_reader :version
 
+      # A symbol representing whether or not we are packing or unpacking.
+      attr_reader :variant
+
+      # A byteslice of the source string that this directive represents.
+      attr_reader :source
+
+      # The type of the directive.
+      attr_reader :type
+
+      # The type of signedness of the directive.
+      attr_reader :signed
+
+      # The type of endianness of the directive.
+      attr_reader :endian
+
+      # The size of the directive.
+      attr_reader :size
+
+      # The length type of this directive (used for integers).
+      attr_reader :length_type
+
+      # The length of this directive (used for integers).
+      attr_reader :length
+
+      # Initialize a new directive with the given values.
       def initialize(version, variant, source, type, signed, endian, size, length_type, length)
         @version = version
         @variant = variant
@@ -71,6 +97,7 @@ def initialize(version, variant, source, type, signed, endian, size, length_type
         @length = length
       end
 
+      # The descriptions of the various types of endianness.
       ENDIAN_DESCRIPTIONS = {
         AGNOSTIC_ENDIAN: "agnostic",
         LITTLE_ENDIAN: "little-endian (VAX)",
@@ -79,12 +106,14 @@ def initialize(version, variant, source, type, signed, endian, size, length_type
         ENDIAN_NA: "n/a"
       }
 
+      # The descriptions of the various types of signedness.
       SIGNED_DESCRIPTIONS = {
         UNSIGNED: "unsigned",
         SIGNED: "signed",
         SIGNED_NA: "n/a"
       }
 
+      # The descriptions of the various types of sizes.
       SIZE_DESCRIPTIONS = {
         SIZE_SHORT: "short",
         SIZE_INT: "int-width",
@@ -97,6 +126,7 @@ def initialize(version, variant, source, type, signed, endian, size, length_type
         SIZE_P: "pointer-width"
       }
 
+      # Provide a human-readable description of the directive.
       def describe
         case type
         when SPACE
@@ -161,15 +191,21 @@ def describe
       end
     end
 
-    # A class used to describe what a pack template does.
+    # The result of parsing a pack template.
     class Format
-      attr_reader :directives, :encoding
+      # A list of the directives in the template.
+      attr_reader :directives
+
+      # The encoding of the template.
+      attr_reader :encoding
 
+      # Create a new Format with the given directives and encoding.
       def initialize(directives, encoding)
         @directives = directives
         @encoding = encoding
       end
 
+      # Provide a human-readable description of the format.
       def describe
         source_width = directives.map { |d| d.source.inspect.length }.max
         directive_lines = directives.map do |directive|