[ruby/prism] Documentation for more C functions

https://github.com/ruby/prism/commit/88336e7d9f

7 files changed, 98 insertions, 63 deletions

diff --git a/prism/prism.c b/prism/prism.c
index 87479ab283..ec86a64fb9 100644
--- a/prism/prism.c
+++ b/prism/prism.c
@@ -15675,8 +15675,8 @@ pm_parser_init(pm_parser_t *parser, const uint8_t *source, size_t size, const ch
         .enclosure_nesting = 0,
         .lambda_enclosure_nesting = -1,
         .brace_nesting = 0,
-        .do_loop_stack = PM_STATE_STACK_EMPTY,
-        .accepts_block_stack = PM_STATE_STACK_EMPTY,
+        .do_loop_stack = 0,
+        .accepts_block_stack = 0,
         .lex_modes = {
             .index = 0,
             .stack = {{ .mode = PM_LEX_DEFAULT }},
@@ -15688,10 +15688,10 @@ pm_parser_init(pm_parser_t *parser, const uint8_t *source, size_t size, const ch
         .current = { .type = PM_TOKEN_EOF, .start = source, .end = source },
         .next_start = NULL,
         .heredoc_end = NULL,
-        .comment_list = PM_LIST_EMPTY,
-        .magic_comment_list = PM_LIST_EMPTY,
-        .warning_list = PM_LIST_EMPTY,
-        .error_list = PM_LIST_EMPTY,
+        .comment_list = { 0 },
+        .magic_comment_list = { 0 },
+        .warning_list = { 0 },
+        .error_list = { 0 },
         .current_scope = NULL,
         .current_context = NULL,
         .encoding = pm_encoding_utf_8,
@@ -15700,7 +15700,7 @@ pm_parser_init(pm_parser_t *parser, const uint8_t *source, size_t size, const ch
         .encoding_comment_start = source,
         .lex_callback = NULL,
         .filepath_string = filepath_string,
-        .constant_pool = PM_CONSTANT_POOL_EMPTY,
+        .constant_pool = { 0 },
         .newline_list = { 0 },
         .integer_base = 0,
         .current_string = PM_STRING_EMPTY,
diff --git a/prism/util/pm_constant_pool.h b/prism/util/pm_constant_pool.h
index fa9081f737..2a2804c8d1 100644
--- a/prism/util/pm_constant_pool.h
+++ b/prism/util/pm_constant_pool.h
@@ -69,9 +69,6 @@ typedef struct {
     uint32_t capacity;
 } pm_constant_pool_t;
 
-// Define an empty constant pool.
-#define PM_CONSTANT_POOL_EMPTY ((pm_constant_pool_t) { .buckets = NULL, .constants = NULL, .size = 0, .capacity = 0 })
-
 // Initialize a new constant pool with a given capacity.
 bool pm_constant_pool_init(pm_constant_pool_t *pool, uint32_t capacity);
 
diff --git a/prism/util/pm_list.c b/prism/util/pm_list.c
index 0c8feea9d8..62cfe47cfa 100644
--- a/prism/util/pm_list.c
+++ b/prism/util/pm_list.c
@@ -1,18 +1,24 @@
 #include "prism/util/pm_list.h"
 
-// Returns true if the given list is empty.
+/**
+ * Returns true if the given list is empty.
+ */
 PRISM_EXPORTED_FUNCTION bool
 pm_list_empty_p(pm_list_t *list) {
     return list->head == NULL;
 }
 
-// Returns the size of the list.
+/**
+ * Returns the size of the list.
+ */
 PRISM_EXPORTED_FUNCTION size_t
 pm_list_size(pm_list_t *list) {
     return list->size;
 }
 
-// Append a node to the given list.
+/**
+ * Append a node to the given list.
+ */
 void
 pm_list_append(pm_list_t *list, pm_list_node_t *node) {
     if (list->head == NULL) {
@@ -25,7 +31,9 @@ pm_list_append(pm_list_t *list, pm_list_node_t *node) {
     list->size++;
 }
 
-// Deallocate the internal state of the given list.
+/**
+ * Deallocate the internal state of the given list.
+ */
 PRISM_EXPORTED_FUNCTION void
 pm_list_free(pm_list_t *list) {
     pm_list_node_t *node = list->head;
diff --git a/prism/util/pm_list.h b/prism/util/pm_list.h
index 19fdec65e3..53a5b9c3a1 100644
--- a/prism/util/pm_list.h
+++ b/prism/util/pm_list.h
@@ -1,30 +1,3 @@
-// This struct represents an abstract linked list that provides common
-// functionality. It is meant to be used any time a linked list is necessary to
-// store data.
-//
-// The linked list itself operates off a set of pointers. Because the pointers
-// are not necessarily sequential, they can be of any size. We use this fact to
-// allow the consumer of this linked list to extend the node struct to include
-// any data they want. This is done by using the pm_list_node_t as the first
-// member of the struct.
-//
-// For example, if we want to store a list of integers, we can do the following:
-//
-//     typedef struct {
-//       pm_list_node_t node;
-//       int value;
-//     } pm_int_node_t;
-//
-//     pm_list_t list = PM_LIST_EMPTY;
-//     pm_int_node_t *node = malloc(sizeof(pm_int_node_t));
-//     node->value = 5;
-//
-//     pm_list_append(&list, &node->node);
-//
-// The pm_list_t struct is used to represent the overall linked list. It
-// contains a pointer to the head and tail of the list. This allows for easy
-// iteration and appending of new nodes.
-
 #ifndef PRISM_LIST_H
 #define PRISM_LIST_H
 
@@ -35,33 +8,83 @@
 #include <stdint.h>
 #include <stdlib.h>
 
-// This represents a node in the linked list.
+/**
+ * This struct represents an abstract linked list that provides common
+ * functionality. It is meant to be used any time a linked list is necessary to
+ * store data.
+ *
+ * The linked list itself operates off a set of pointers. Because the pointers
+ * are not necessarily sequential, they can be of any size. We use this fact to
+ * allow the consumer of this linked list to extend the node struct to include
+ * any data they want. This is done by using the pm_list_node_t as the first
+ * member of the struct.
+ *
+ * For example, if we want to store a list of integers, we can do the following:
+ *
+ *     typedef struct {
+ *         pm_list_node_t node;
+ *         int value;
+ *     } pm_int_node_t;
+ *
+ *     pm_list_t list = { 0 };
+ *     pm_int_node_t *node = malloc(sizeof(pm_int_node_t));
+ *     node->value = 5;
+ *
+ *     pm_list_append(&list, &node->node);
+ *
+ * The pm_list_t struct is used to represent the overall linked list. It
+ * contains a pointer to the head and tail of the list. This allows for easy
+ * iteration and appending of new nodes.
+ */
 typedef struct pm_list_node {
+    /** A pointer to the next node in the list. */
     struct pm_list_node *next;
 } pm_list_node_t;
 
-// This represents the overall linked list. It keeps a pointer to the head and
-// tail so that iteration is easy and pushing new nodes is easy.
+/**
+ * This represents the overall linked list. It keeps a pointer to the head and
+ * tail so that iteration is easy and pushing new nodes is easy.
+ */
 typedef struct {
+    /** The size of the list. */
     size_t size;
+
+    /** A pointer to the head of the list. */
     pm_list_node_t *head;
+
+    /** A pointer to the tail of the list. */
     pm_list_node_t *tail;
 } pm_list_t;
 
-// This represents an empty list. It's used to initialize a stack-allocated list
-// as opposed to a method call.
-#define PM_LIST_EMPTY ((pm_list_t) { .size = 0, .head = NULL, .tail = NULL })
-
-// Returns true if the given list is empty.
+/**
+ * Returns true if the given list is empty.
+ *
+ * @param list The list to check.
+ * @return True if the given list is empty, otherwise false.
+ */
 PRISM_EXPORTED_FUNCTION bool pm_list_empty_p(pm_list_t *list);
 
-// Returns the size of the list.
+/**
+ * Returns the size of the list.
+ *
+ * @param list The list to check.
+ * @return The size of the list.
+ */
 PRISM_EXPORTED_FUNCTION size_t pm_list_size(pm_list_t *list);
 
-// Append a node to the given list.
+/**
+ * Append a node to the given list.
+ *
+ * @param list The list to append to.
+ * @param node The node to append.
+ */
 void pm_list_append(pm_list_t *list, pm_list_node_t *node);
 
-// Deallocate the internal state of the given list.
+/**
+ * Deallocate the internal state of the given list.
+ *
+ * @param list The list to free.
+ */
 PRISM_EXPORTED_FUNCTION void pm_list_free(pm_list_t *list);
 
 #endif
diff --git a/prism/util/pm_memchr.c b/prism/util/pm_memchr.c
index c5dd2e8655..b2049250e4 100644
--- a/prism/util/pm_memchr.c
+++ b/prism/util/pm_memchr.c
@@ -2,9 +2,11 @@
 
 #define PRISM_MEMCHR_TRAILING_BYTE_MINIMUM 0x40
 
-// We need to roll our own memchr to handle cases where the encoding changes and
-// we need to search for a character in a buffer that could be the trailing byte
-// of a multibyte character.
+/**
+ * We need to roll our own memchr to handle cases where the encoding changes and
+ * we need to search for a character in a buffer that could be the trailing byte
+ * of a multibyte character.
+ */
 void *
 pm_memchr(const void *memory, int character, size_t number, bool encoding_changed, pm_encoding_t *encoding) {
     if (encoding_changed && encoding->multibyte && character >= PRISM_MEMCHR_TRAILING_BYTE_MINIMUM) {
diff --git a/prism/util/pm_memchr.h b/prism/util/pm_memchr.h
index fdc55a730b..6b817a5521 100644
--- a/prism/util/pm_memchr.h
+++ b/prism/util/pm_memchr.h
@@ -6,9 +6,19 @@
 
 #include <stddef.h>
 
-// We need to roll our own memchr to handle cases where the encoding changes and
-// we need to search for a character in a buffer that could be the trailing byte
-// of a multibyte character.
+/**
+ * We need to roll our own memchr to handle cases where the encoding changes and
+ * we need to search for a character in a buffer that could be the trailing byte
+ * of a multibyte character.
+ *
+ * @param source The source string.
+ * @param character The character to search for.
+ * @param number The maximum number of bytes to search.
+ * @param encoding_changed Whether the encoding changed.
+ * @param encoding A pointer to the encoding.
+ * @return A pointer to the first occurrence of the character in the source
+ *     string, or NULL if no such character exists.
+ */
 void * pm_memchr(const void *source, int character, size_t number, bool encoding_changed, pm_encoding_t *encoding);
 
 #endif
diff --git a/prism/util/pm_state_stack.h b/prism/util/pm_state_stack.h
index 268243085a..7268a3fd63 100644
--- a/prism/util/pm_state_stack.h
+++ b/prism/util/pm_state_stack.h
@@ -12,11 +12,6 @@
 typedef uint32_t pm_state_stack_t;
 
 /**
- * Initializes the state stack to an empty stack.
- */
-#define PM_STATE_STACK_EMPTY ((pm_state_stack_t) 0)
-
-/**
  * Pushes a value onto the stack.
  *
  * @param stack The stack to push the value onto.