diff --git a/include/prism/node.h b/include/prism/node.h index 5a6fcf3d25f..768ddec1b0e 100644 --- a/include/prism/node.h +++ b/include/prism/node.h @@ -4,24 +4,49 @@ #include "prism/defines.h" #include "prism/parser.h" -// Append a new node onto the end of the node list. +/** + * Append a new node onto the end of the node list. + * + * @param list The list to append to. + * @param node The node to append. + */ void pm_node_list_append(pm_node_list_t *list, pm_node_t *node); -// Deallocate a node and all of its children. +/** + * Deallocate a node and all of its children. + * + * @param parser The parser that owns the node. + * @param node The node to deallocate. + */ PRISM_EXPORTED_FUNCTION void pm_node_destroy(pm_parser_t *parser, struct pm_node *node); -// This struct stores the information gathered by the pm_node_memsize function. -// It contains both the memory footprint and additionally metadata about the -// shape of the tree. +/** + * This struct stores the information gathered by the pm_node_memsize function. + * It contains both the memory footprint and additionally metadata about the + * shape of the tree. + */ typedef struct { + /** The total memory footprint of the node and all of its children. */ size_t memsize; + + /** The number of children the node has. */ size_t node_count; } pm_memsize_t; -// Calculates the memory footprint of a given node. +/** + * Calculates the memory footprint of a given node. + * + * @param node The node to calculate the memory footprint of. + * @param memsize The memory footprint of the node and all of its children. + */ PRISM_EXPORTED_FUNCTION void pm_node_memsize(pm_node_t *node, pm_memsize_t *memsize); -// Returns a string representation of the given node type. +/** + * Returns a string representation of the given node type. + * + * @param node_type The node type to convert to a string. + * @return A string representation of the given node type. + */ PRISM_EXPORTED_FUNCTION const char * pm_node_type_to_str(pm_node_type_t node_type); -#endif // PRISM_NODE_H +#endif diff --git a/templates/src/node.c.erb b/templates/src/node.c.erb index 841e1ac0369..0f3a6d8af2a 100644 --- a/templates/src/node.c.erb +++ b/templates/src/node.c.erb @@ -4,7 +4,9 @@ static void pm_node_memsize_node(pm_node_t *node, pm_memsize_t *memsize); -// Calculate the size of the node list in bytes. +/** + * Calculate the size of the node list in bytes. + */ static size_t pm_node_list_memsize(pm_node_list_t *node_list, pm_memsize_t *memsize) { size_t size = sizeof(pm_node_list_t) + (node_list->capacity * sizeof(pm_node_t *)); @@ -14,7 +16,9 @@ pm_node_list_memsize(pm_node_list_t *node_list, pm_memsize_t *memsize) { return size; } -// Append a new node onto the end of the node list. +/** + * Append a new node onto the end of the node list. + */ void pm_node_list_append(pm_node_list_t *list, pm_node_t *node) { if (list->size == list->capacity) { @@ -27,8 +31,10 @@ pm_node_list_append(pm_node_list_t *list, pm_node_t *node) { PRISM_EXPORTED_FUNCTION void pm_node_destroy(pm_parser_t *parser, pm_node_t *node); -// Deallocate the inner memory of a list of nodes. The parser argument is not -// used, but is here for the future possibility of pre-allocating memory pools. +/** + * Deallocate the inner memory of a list of nodes. The parser argument is not + * used, but is here for the future possibility of pre-allocating memory pools. + */ static void pm_node_list_free(pm_parser_t *parser, pm_node_list_t *list) { if (list->capacity > 0) { @@ -39,9 +45,11 @@ pm_node_list_free(pm_parser_t *parser, pm_node_list_t *list) { } } -// Deallocate the space for a pm_node_t. Similarly to pm_node_alloc, we're not -// using the parser argument, but it's there to allow for the future possibility -// of pre-allocating larger memory pools. +/** + * Deallocate the space for a pm_node_t. Similarly to pm_node_alloc, we're not + * using the parser argument, but it's there to allow for the future possibility + * of pre-allocating larger memory pools. + */ PRISM_EXPORTED_FUNCTION void pm_node_destroy(pm_parser_t *parser, pm_node_t *node) { switch (PM_NODE_TYPE(node)) { @@ -129,14 +137,18 @@ pm_node_memsize_node(pm_node_t *node, pm_memsize_t *memsize) { } } -// Calculates the memory footprint of a given node. +/** + * Calculates the memory footprint of a given node. + */ PRISM_EXPORTED_FUNCTION void pm_node_memsize(pm_node_t *node, pm_memsize_t *memsize) { *memsize = (pm_memsize_t) { .memsize = 0, .node_count = 0 }; pm_node_memsize_node(node, memsize); } -// Returns a string representation of the given node type. +/** + * Returns a string representation of the given node type. + */ PRISM_EXPORTED_FUNCTION const char * pm_node_type_to_str(pm_node_type_t node_type) {