[ruby/prism] Documentation for nodes

https://github.com/ruby/prism/commit/69323d3df4

1 files changed, 33 insertions, 8 deletions

diff --git a/prism/node.h b/prism/node.h
index 5a6fcf3d25..768ddec1b0 100644
--- a/prism/node.h
+++ b/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