From e8a72b516f141de9581c2edd1d8eb101739477bb Mon Sep 17 00:00:00 2001 From: Kevin Newton Date: Mon, 30 Oct 2023 23:28:54 -0400 Subject: [ruby/prism] Documentation for more C functions https://github.com/ruby/prism/commit/88336e7d9f --- prism/prism.c | 14 +++--- prism/util/pm_constant_pool.h | 3 -- prism/util/pm_list.c | 16 +++++-- prism/util/pm_list.h | 99 ++++++++++++++++++++++++++----------------- prism/util/pm_memchr.c | 8 ++-- prism/util/pm_memchr.h | 16 +++++-- prism/util/pm_state_stack.h | 5 --- 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 #include -// 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 -// 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 @@ -11,11 +11,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. * -- cgit v1.2.3