*: documentation

src/arl/lib/sv.h

@@ -16,12 +16,21 @@ typedef struct
   u64 size;
 } sv_t;
 
+// Constructor and printer macros
 #define SV(PTR, SIZE) ((sv_t){.data = (PTR), .size = (SIZE)})
 #define PR_SV         "%.*s"
 #define SV_FMT(SV)    (int)((SV).size), (SV).data
+
+// Return a new string view which has had LEN characters removed from the
+// beginning
 sv_t sv_chop_left(sv_t sv, u64 len);
+// Return a new string view which has had LEN characters removed from the end
 sv_t sv_chop_right(sv_t sv, u64 len);
+// Return the first index where SV does not present a character from EXPECTED
+// (strspn equivalent)
 u64 sv_while(const sv_t sv, const char *expected);
+// Return the first index where SV presents a character from EXPECTED (strcspn
+// equivalent)
 u64 sv_till(const sv_t sv, const char *expected);
 
 #endif

src/arl/lib/vec.h

@@ -28,16 +28,27 @@ typedef struct
     alignas(max_align_t) u8 inlined[VEC_INLINE_CAPACITY];
   };
 } vec_t;
+
 static_assert(sizeof(vec_t) == 64, "Expected sizeof(vec_t) to be 64");
 
 void vec_append(vec_t *vec, const void *const ptr, u64 size);
 void vec_append_byte(vec_t *vec, u8 byte);
+
+// Returns pointer to the start of the buffer VEC is currently using to store
+// data (either its inline buffer or the heap buffer).
 void *vec_data(vec_t *vec);
+
+// Ensure VEC has at least CAPACITY capacity.
 void vec_ensure_capacity(vec_t *vec, u64 capacity);
+
+// Ensure VEC has at least SIZE bytes free
 void vec_ensure_free(vec_t *vec, u64 size);
 void vec_free(vec_t *vec);
+
+// Copy all data from V1 into V2.
 void vec_clone(vec_t *v2, vec_t *v1);
 
+// Helper macro to use a vector as a type generic (but homogeneous) container.
 #define VEC_GET(VEC, INDEX, TYPE) (((TYPE *)vec_data(VEC))[INDEX])
 
 #endif

src/arl/parser/ast.h

@@ -12,12 +12,14 @@
 #include <arl/lib/sv.h>
 #include <arl/lib/vec.h>
 
+/// Types the AST can encode
 typedef enum
 {
   TYPE_SYMBOL,
   TYPE_STRING,
 } type_t;
 
+/// Node of the AST as a tagged union
 typedef struct
 {
   u64 byte;
@@ -29,12 +31,13 @@ typedef struct
   } value;
 } obj_t;
 
+// Constructors
 obj_t obj_string(u64 byte, sv_t string);
 obj_t obj_symbol(u64 byte, sv_t symbol);
+
 void obj_print(FILE *fp, obj_t *obj);
 
-// Our AST is simply a vector of objects.  Nesting and tree like structure is
-// imposed by individual objects.
+/// The AST as a flat collection of nodes
 typedef struct
 {
   vec_t objects;

src/arl/parser/parser.c

@@ -22,8 +22,6 @@ const char *parse_err_to_string(parse_err_t err)
   {
   case PARSE_ERR_OK:
     return "OK";
-  case PARSE_ERR_UNEXPECTED_EOF:
-    return "UNEXPECTED_EOF";
   case PARSE_ERR_EXPECTED_SPEECH_MARKS:
     return "EXPECTED_SPEECH_MARKS";
   case PARSE_ERR_UNKNOWN_CHAR:

src/arl/parser/parser.h

@@ -10,24 +10,30 @@
 
 #include <arl/parser/ast.h>
 
-typedef enum
-{
-  PARSE_ERR_OK = 0,
-  PARSE_ERR_UNEXPECTED_EOF,
-  PARSE_ERR_EXPECTED_SPEECH_MARKS,
-  PARSE_ERR_UNKNOWN_CHAR,
-} parse_err_t;
-const char *parse_err_to_string(parse_err_t err);
-
+/// Parser streams, utilised when generating an AST.
 typedef struct
 {
   u64 byte;
   sv_t contents;
 } parse_stream_t;
 
-void parse_stream_get_line_col(parse_stream_t *stream, u64 *line, u64 *col);
+/// Types of errors that may occur during parsing
+typedef enum
+{
+  PARSE_ERR_OK = 0,
+  PARSE_ERR_EXPECTED_SPEECH_MARKS,
+  PARSE_ERR_UNKNOWN_CHAR,
+} parse_err_t;
+const char *parse_err_to_string(parse_err_t err);
+
+// Generates an AST from STREAM, storing it in OUT.  Returns any errors it may
+// generate.
 parse_err_t parse(ast_t *out, parse_stream_t *stream);
 
+// Computes the line and column that STREAM is currently pointing at in its
+// buffer, storing it in LINE and COL.
+void parse_stream_get_line_col(parse_stream_t *stream, u64 *line, u64 *col);
+
 #endif
 
 /* Copyright (C) 2026 Aryadev Chavali