More file comments

27 files changed, 57 insertions, 16 deletions

diff --git a/builtins/array.c b/builtins/array.c
index 2fd66f58..3380d4d3 100644
--- a/builtins/array.c
+++ b/builtins/array.c
@@ -1,3 +1,4 @@
+// Functions that operate on arrays
 
 #include <ctype.h>
 #include <err.h>
diff --git a/builtins/array.h b/builtins/array.h
index c2c0b8b6..209a72e2 100644
--- a/builtins/array.h
+++ b/builtins/array.h
@@ -1,4 +1,7 @@
 #pragma once
+
+// Functions that operate on arrays
+
 #include <stdbool.h>
 #include <gc/cord.h>
 
diff --git a/builtins/bool.c b/builtins/bool.c
index 35eaafec..5831845d 100644
--- a/builtins/bool.c
+++ b/builtins/bool.c
@@ -1,4 +1,4 @@
-
+// Boolean methods/type info
 #include <gc.h>
 #include <gc/cord.h>
 #include <stdbool.h>
diff --git a/builtins/bool.h b/builtins/bool.h
index 08b4126a..1462e7d6 100644
--- a/builtins/bool.h
+++ b/builtins/bool.h
@@ -1,4 +1,7 @@
 #pragma once
+
+// Boolean functions/type info
+
 #include <gc/cord.h>
 #include <stdbool.h>
 #include <stdint.h>
diff --git a/builtins/color.c b/builtins/color.c
index 4732382a..d79aa9ef 100644
--- a/builtins/color.c
+++ b/builtins/color.c
@@ -1,4 +1,4 @@
-
+// Logic for detecting whether console color should be used
 #include <stdbool.h>
 #include <stdlib.h>
 #include <string.h>
diff --git a/builtins/color.h b/builtins/color.h
index d9e5c9f1..26e912d8 100644
--- a/builtins/color.h
+++ b/builtins/color.h
@@ -1,5 +1,7 @@
 #pragma once
 
+// Logic for console color usage
+
 #include <stdbool.h>
 
 extern bool USE_COLOR;
diff --git a/builtins/datatypes.h b/builtins/datatypes.h
index 20dede35..738dc5c3 100644
--- a/builtins/datatypes.h
+++ b/builtins/datatypes.h
@@ -1,4 +1,7 @@
 #pragma once
+
+// Common datastructures (arrays, tables, closures)
+
 #include <stdint.h>
 #include <stdbool.h>
 
diff --git a/builtins/functions.c b/builtins/functions.c
index 2bd47286..71fbfd63 100644
--- a/builtins/functions.c
+++ b/builtins/functions.c
@@ -1,3 +1,4 @@
+// Built-in functions
 #include <gc.h>
 #include <gc/cord.h>
 #include <stdbool.h>
diff --git a/builtins/functions.h b/builtins/functions.h
index ca849048..7deaf2b0 100644
--- a/builtins/functions.h
+++ b/builtins/functions.h
@@ -1,5 +1,7 @@
 #pragma once
 
+// Built-in functions
+
 #include <gc/cord.h>
 #include <stdbool.h>
 #include <stdint.h>
diff --git a/builtins/integers.c b/builtins/integers.c
index 4116879e..57f678ec 100644
--- a/builtins/integers.c
+++ b/builtins/integers.c
@@ -1,3 +1,4 @@
+// Integer type infos and methods
 #include <gc.h>
 #include <gc/cord.h>
 #include <stdbool.h>
diff --git a/builtins/integers.h b/builtins/integers.h
index 79ce2643..35a579bf 100644
--- a/builtins/integers.h
+++ b/builtins/integers.h
@@ -1,4 +1,7 @@
 #pragma once
+
+// Integer type infos and methods
+
 #include <gc/cord.h>
 #include <stdbool.h>
 #include <stdint.h>
diff --git a/builtins/macros.h b/builtins/macros.h
index 09896b0d..6128480a 100644
--- a/builtins/macros.h
+++ b/builtins/macros.h
@@ -1,14 +1,9 @@
 #pragma once
 
+// A few helper macros
+
 #include <gc.h>
-#include <gc/cord.h>
-#include <signal.h>
-#include <stdbool.h>
-#include <stdint.h>
-#include <stdio.h>
-#include <stdlib.h>
 #include <string.h>
-#include <unistd.h>
 
 #define $heap(x) (__typeof(x)*)memcpy(GC_MALLOC(sizeof(x)), (__typeof(x)[1]){x}, sizeof(x))
 #define $stack(x) (__typeof(x)*)((__typeof(x)[1]){x})
diff --git a/builtins/memory.c b/builtins/memory.c
index f33196be..290a6f1b 100644
--- a/builtins/memory.c
+++ b/builtins/memory.c
@@ -1,4 +1,4 @@
-
+// Type info and methods for "Memory" opaque type
 #include <gc.h>
 #include <gc/cord.h>
 #include <stdbool.h>
diff --git a/builtins/memory.h b/builtins/memory.h
index af923837..b5519027 100644
--- a/builtins/memory.h
+++ b/builtins/memory.h
@@ -1,4 +1,7 @@
 #pragma once
+
+// Type info and methods for "Memory" opaque type
+
 #include <gc/cord.h>
 #include <stdbool.h>
 #include <stdint.h>
diff --git a/builtins/nums.c b/builtins/nums.c
index b05c6fab..f4e5cc99 100644
--- a/builtins/nums.c
+++ b/builtins/nums.c
@@ -1,3 +1,5 @@
+// Type infos and methods for Nums (floating point)
+
 #include <float.h>
 #include <gc.h>
 #include <gc/cord.h>
diff --git a/builtins/nums.h b/builtins/nums.h
index ce41c086..97d72c50 100644
--- a/builtins/nums.h
+++ b/builtins/nums.h
@@ -1,4 +1,7 @@
 #pragma once
+
+// Type infos and methods for Nums (floating point)
+
 #include <gc/cord.h>
 #include <math.h>
 #include <stdbool.h>
diff --git a/builtins/pointer.c b/builtins/pointer.c
index d490485f..a894e6a5 100644
--- a/builtins/pointer.c
+++ b/builtins/pointer.c
@@ -1,4 +1,4 @@
-
+// Type infos and methods for Pointer types
 #include <ctype.h>
 #include <err.h>
 #include <gc.h>
diff --git a/builtins/pointer.h b/builtins/pointer.h
index 32cf365b..edaaaa21 100644
--- a/builtins/pointer.h
+++ b/builtins/pointer.h
@@ -1,4 +1,7 @@
 #pragma once
+
+// Type infos and methods for Pointer types
+
 #include <gc/cord.h>
 #include <stdbool.h>
 #include <stdint.h>
diff --git a/builtins/table.c b/builtins/table.c
index be4444ac..03f3e6b3 100644
--- a/builtins/table.c
+++ b/builtins/table.c
@@ -1,6 +1,5 @@
-
-// table.c - C Hash table implementation for SSS
-// Copyright 2023 Bruce Hill
+// table.c - C Hash table implementation
+// Copyright 2024 Bruce Hill
 // Provided under the MIT license with the Commons Clause
 // See included LICENSE for details.
 
diff --git a/builtins/table.h b/builtins/table.h
index 6577782d..a29fa7cc 100644
--- a/builtins/table.h
+++ b/builtins/table.h
@@ -1,4 +1,7 @@
 #pragma once
+
+// Hash table datastructure with methods and type information
+
 #include <stdint.h>
 #include <stdbool.h>
 #include <string.h>
diff --git a/builtins/text.c b/builtins/text.c
index 7116c92f..a0d2f6bc 100644
--- a/builtins/text.c
+++ b/builtins/text.c
@@ -1,3 +1,5 @@
+// Type info and methods for Text datatype, which uses the Boehm "cord" library
+// and libunistr
 #include <assert.h>
 #include <ctype.h>
 #include <err.h>
diff --git a/builtins/text.h b/builtins/text.h
index 4c206cbb..edbd119c 100644
--- a/builtins/text.h
+++ b/builtins/text.h
@@ -1,4 +1,8 @@
 #pragma once
+
+// Type info and methods for Text datatype, which uses the Boehm "cord" library
+// and libunistr
+
 #include <gc/cord.h>
 #include <stdbool.h>
 #include <stdint.h>
diff --git a/builtins/tomo.h b/builtins/tomo.h
index 2676037f..03817e0f 100644
--- a/builtins/tomo.h
+++ b/builtins/tomo.h
@@ -1,5 +1,8 @@
 #pragma once
 
+// All of the different builtin modules can be included by including this one
+// import
+
 #include <err.h>
 #include <gc.h>
 #include <gc/cord.h>
diff --git a/builtins/types.c b/builtins/types.c
index 72be5afa..6850e3d7 100644
--- a/builtins/types.c
+++ b/builtins/types.c
@@ -1,4 +1,4 @@
-// Generic type constructor
+// Type information and methods for TypeInfos (i.e. runtime representations of types)
 #include <err.h>
 #include <gc.h>
 #include <stdlib.h>
diff --git a/builtins/types.h b/builtins/types.h
index f62e37e0..bf94b526 100644
--- a/builtins/types.h
+++ b/builtins/types.h
@@ -1,4 +1,7 @@
 #pragma once
+
+// Type information and methods for TypeInfos (i.e. runtime representations of types)
+
 #include <gc/cord.h>
 #include <stdbool.h>
 #include <stdint.h>
diff --git a/builtins/util.c b/builtins/util.c
index 16ef7aaf..c859279e 100644
--- a/builtins/util.c
+++ b/builtins/util.c
@@ -1,3 +1,4 @@
+// Built-in utility functions
 #include <ctype.h>
 #include <gc.h>
 #include <gc/cord.h>
@@ -80,5 +81,4 @@ CORD CORD_asprintf(CORD fmt, ...)
     return c;
 }
 
-
 // vim: ts=4 sw=0 et cino=L2,l1,(0,W4,m1,\:0
diff --git a/builtins/util.h b/builtins/util.h
index c858f6ce..9c8d8e9e 100644
--- a/builtins/util.h
+++ b/builtins/util.h
@@ -1,5 +1,7 @@
 #pragma once
 
+// Built-in utility functions
+
 #include <assert.h>
 #include <gc.h>
 #include <gc/cord.h>