Documentation for nodes

ruby · Nov 1, 2023 · 69323d3 · 69323d3
1 parent 271f3bf
commit 69323d3
Show file tree

Hide file tree

Showing 2 changed files with 54 additions and 17 deletions.
diff --git 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
@@ -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)
 {