Reformatted comments to be more consistent & clear.

src/include/ast.h

@@ -3,6 +3,7 @@
 
 #include <stdlib.h>
 
+// The type of an `AST`.
 typedef enum {
     // Primitive types.
     AST_TYPE_NUM, // A number (float).
@@ -24,26 +25,38 @@ typedef enum {
     AST_TYPE_MAX = AST_TYPE_BLOCK,
 } ASTType;
 
+// An Abstract Syntax Tree.
 typedef struct {
-    ASTType type;
-    void* data;
+    ASTType type; // The type of the `AST`.
+    void* data;   // The data of the `AST`.
 } AST;
 
+// Create a new `AST`.
 AST* ast_init(ASTType type, void* data);
+// Destroy an `AST`, recursively.
 void ast_destroy(AST* ast);
+// Print an `AST`, recursively.
 void ast_print(AST* ast);
+// Helper function to `ast_print()`, where `i` is indentation level.
 void ast_print_i(AST* ast, int i);
 
+// A number.
 typedef double ASTNumData;
 
+// Create a new `ASTNumData`.
 ASTNumData* ast_num_data_init(double val);
+// Destroy an `ASTNumData`.
 void ast_num_data_destroy(ASTNumData* num);
+// Print an `ASTNumData`.
 void ast_num_print(ASTNumData*, int i);
 
 // An exception.
 typedef char* ASTExcData;
+// Create a new `ASTExecData.
 ASTExcData ast_exc_data_init(char* msg);
+// Destroy an `ASTExecData`.
 void ast_exc_data_destroy(ASTExcData* exc);
+// Print an `ASTExecData`.
 void ast_exc_print(ASTExcData, int i);
 
 // A built-in function.
@@ -54,14 +67,18 @@ ASTBIFData* ast_bif_data_init(AST* fn(size_t, AST**));
 
 // There is no `ASTBIFData` destroy function, as function pointers are immortal.
 
+// A call (to a function).
 typedef struct {
     char* to;    // What the call's to.
     size_t argc; // Argument count.
     AST** argv;  // Argument vector.
 } ASTCallData;
 
+// Create a new `ASTCallData`.
 ASTCallData* ast_call_data_init(char* to, size_t argc, AST** argv);
+// Destroy an `ASTCallData`.
 void ast_call_data_destroy(ASTCallData* call);
+// Print an `ASTCallData`.
 void ast_call_print(ASTCallData*, int i);
 
 // A variable definition's data.
@@ -70,9 +87,11 @@ typedef struct {
     AST* val;
 } ASTVDefData;
 
+// Create a new `ASTVDefData`.
 ASTVDefData* ast_vdef_data_init(char* name, AST* val);
-// Destroys the vdef, its name, and its ->val.
+// Destroys the `ASTVDefData`, `ASTVDefData->name`, and `ASTVDefData->val`.
 void ast_vdef_data_destroy(ASTVDefData* vdef);
+// Print an `ASTVDefData`.
 void ast_vdef_print(ASTVDefData*, int depth);
 
 // A variable reference's data.
@@ -80,18 +99,24 @@ typedef struct {
     char* to; // What the reference's to.
 } ASTVrefData;
 
+// Create a new `ASTVRefData`.
 ASTVrefData* ast_vref_data_init(char* to);
+// Destroy an `ASTVRefData`.
 void ast_vref_data_destroy(ASTVrefData* call);
+// Print an `ASTVRefData`.
 void ast_vref_print(ASTVrefData*, int i);
 
+// A code block.
 typedef struct {
     AST** inside; // What's inside the block.
     size_t ln;    // How many ASTs are in the block.
 } ASTBlockData;
 
+// Create a new `ASTBlockData`.
 ASTBlockData* ast_block_data_init(AST** inside, size_t ln);
-// Destroy a block. Also destroy all ASTs inside.
+// Destroy an `ASTBlockData`, recursively.
 void ast_block_data_destroy(ASTBlockData* block);
+// Print an `ASTBlockData`.
 void ast_block_print(ASTBlockData*, int i);
 
 #endif

src/include/dlist.h

@@ -11,12 +11,14 @@ typedef struct {
     size_t ln;  // The number of elements in the list.
 } DList;
 
+// Create a new `DList`.
 DList* dlist_init(void);
+// Destroy a `DList`.
 void dlist_destroy(DList* dstr);
-// Destroy DList structure but preserve ->buf.
+// Destroy `DList` structure but preserve `->buf`.
 void dlist_destroypsv(DList* dstr);
 
-// Append src to dest.
+// Append `src` to `dest`.
 void dlist_append(DList* dest, void* src);
 
 #endif

src/include/dstr.h

@@ -11,15 +11,17 @@ typedef struct {
     size_t ln; // The number of characters in the buffer.
 } Dstr;
 
+// Initialize a `DStr`.
 Dstr* dstr_init(void);
+// Destroy a `DStr`.
 void dstr_destroy(Dstr* dstr);
-// Destroy Dstr structure but preserve ->buf.
+// Destroy `DStr` structure but preserve `DStr->buf`.
 void dstr_destroypsv(Dstr* dstr);
 
-// Append ln characters of src to dest.
+// Append `ln` characters of `src` to `dest`.
 void dstr_append(Dstr* dest, char* src, size_t ln);
 
-// Append ch to dest.
+// Append `ch` to `dest`.
 void dstr_appendch(Dstr* dest, char ch);
 
 #endif

src/include/exec.h

@@ -9,11 +9,17 @@ extern Stack* scope;
 
 // Start executing at the root of the AST. Initialize the `scope`.
 AST* exec_start(AST* ast);
+// Execute an expression. Delegates to the other executor functions.
 AST* exec_exp(AST* ast);
+// Execute the expressions of a block.
 AST* exec_block(AST* ast);
+// Execute a call.
 AST* exec_call(AST* ast);
+// Execute a variable reference.
 AST* exec_vref(AST* ast);
+// Execute a variable definition.
 AST* exec_vdef(AST* ast);
+// Print the result of an execution.
 void exec_print(double n);
 
 #endif

src/include/fnv1a.h

@@ -12,6 +12,7 @@
 // Offset basis.
 #define FNV1A_BASIS_64 0xcbf29ce484222325u
 
+// Hash a string `str` of length `ln`.
 uint64_t fnv1a_hash(char* str, size_t ln);
 
 #endif

src/include/util.h

@@ -1,6 +1,9 @@
 #ifndef UTIL_H
 #define UTIL_H
 
+// Most of this file is cursed printing macros for `ast_print()`. Do not attempt
+// to comprehend.
+
 #ifdef DBG // Debug macros
 
 // Log a message.