Begin moving documentation to headers.

src/include/Array.h

@@ -25,45 +25,140 @@
 #ifndef TELODENDRIA_ARRAY_H
 #define TELODENDRIA_ARRAY_H
 
+/***
+ * @Nm Array
+ * @Nd A simple dynamic array data structure.
+ * @Dd November 24 2022
+ * @Xr HashMap Queue
+ *
+ * These functions implement a simple array data structure that is
+ * automatically resized as necessary when new values are added.  This
+ * implementation does not actually store the values of the items in it;
+ * it only stores pointers to the data. As such, you will still have to
+ * manually maintain all your data. The advantage of this is that these
+ * functions don't have to copy data, and thus don't care how big the
+ * data is. Furthermore, arbitrary data can be stored in the array.
+ * .Pp
+ * This array implementation is optimized for storage space and
+ * appending. Deletions are expensive in that all the items of the list
+ * above a deletion are moved down to fill the hole where the deletion
+ * occurred. Insertions are also expensive in that all the elements
+ * above the given index must be shifted up to make room for the new
+ * element.
+ * .Pp
+ * Due to these design choices, this array implementation is best
+ * suited to linear writing, and then linear or random reading.
+ */
+
 #include <stddef.h>
 #include <stdarg.h>
 
+/**
+ * The functions in this API operate on an array structure which is
+ * opaque to the caller.
+ */
 typedef struct Array Array;
 
-extern Array *
- ArrayCreate(void);
+/**
+ * Allocate a new array. This function returns a pointer that can be
+ * used with the other functions in this API, or NULL if there was an
+ * error allocating memory for the array.
+ */
+extern Array * ArrayCreate(void);
 
-extern size_t
- ArraySize(Array *);
+/**
+ * Deallocate an array. Note that this function does not free any of
+ * the values stored in the array; it is the caller's job to manage the
+ * memory for each item. Typically, the caller would iterate over all
+ * the items in the array and free them before freeing the array.
+ */
+extern void ArrayFree(Array *);
 
-extern void *
- ArrayGet(Array *, size_t);
+/**
+ * Get the size, in number of elements, of the given array.
+ */
+extern size_t ArraySize(Array *);
 
-extern int
- ArrayInsert(Array *, size_t, void *);
+/**
+ * Get the element at the specified index from the specified array.
+ * This function will return NULL if the array is NULL, or the index
+ * is out of bounds. Otherwise, it will return a pointer to a value
+ * put into the array using
+ * .Fn ArrayInsert
+ * or
+ * .Fn ArraySet .
+ */
+extern void * ArrayGet(Array *, size_t);
 
-extern void *
- ArraySet(Array *, size_t, void *);
+/**
+ * Insert the specified element at the specified index in the specified
+ * array. This function will shift the element currently at that index,
+ * and any elements after it before inserting the given element.
+ * .Pp
+ * This function returns a boolean value indicating whether or not it
+ * suceeded.
+ */
+extern int ArrayInsert(Array *, size_t, void *);
 
-extern int
- ArrayAdd(Array *, void *);
+/**
+ * Set the value at the specified index in the specified array to the
+ * specified value. This function will return the old value at that
+ * index, if any.
+ */
+extern void * ArraySet(Array *, size_t, void *);
 
-extern void *
- ArrayDelete(Array *, size_t);
+/**
+ * Append the specified element to the end of the specified array. This
+ * function uses
+ * .Fn ArrayInsert
+ * under the hood to insert an element at the end. It thus has the same
+ * return value as
+ * .Fn ArrayInsert .
+ */
+extern int ArrayAdd(Array *, void *);
 
-extern void
- ArraySort(Array *, int (*) (void *, void *));
+/**
+ * Remove the element at the specified index from the specified array.
+ * This function returns the element removed, if any.
+ */
+extern void * ArrayDelete(Array *, size_t);
 
-extern void
- ArrayFree(Array *);
+/**
+ * Sort the specified array using the specified sort function. The
+ * sort function compares two elements. It takes two void pointers as
+ * parameters, and returns an integer. The return value indicates to
+ * the sorting algorithm how the elements relate to each other. A
+ * return value of 0 indicates that the elements are identical. A
+ * return value greater than 0 indicates that the first item is
+ * ``bigger'' than the second item and should thus appear after it in
+ * the array. A return value less than 0 indicates the opposite: the
+ * second element should appear after the first in the array.
+ */
+extern void ArraySort(Array *, int (*) (void *, void *));
 
-extern int
- ArrayTrim(Array *);
+/**
+ * If possible, reduce the amount of memory allocated to this array
+ * by calling
+ * .Fn Realloc
+ * on the internal structure to perfectly fit the elements in the
+ * array. This function is intended to be used by functions that return
+ * relatively read-only arrays that will be long-lived.
+ */
+extern int ArrayTrim(Array *);
 
-extern Array *
- ArrayFromVarArgs(size_t, va_list);
+/**
+ * Convert a variadic arguments list into an Array. In most cases, the
+ * Array API is much easier to work with than
+ * .Fn va_arg
+ * and friends.
+ */
+extern Array * ArrayFromVarArgs(size_t, va_list);
 
-extern Array *
- ArrayDuplicate(Array *);
+/**
+ * Duplicate an existing array. Note that arrays only hold pointers to
+ * their data, not the data itself, so the duplicated array will point
+ * to the same places in memory as the original array.
+ */
+extern Array * ArrayDuplicate(Array *);
 
 #endif                             /* TELODENDRIA_ARRAY_H */

src/include/Sha2.h

@@ -25,7 +25,26 @@
 #ifndef TELODENDRIA_SHA2_H
 #define TELODENDRIA_SHA2_H
 
-extern char *
- Sha256(char *);
+/***
+ * @Nm Sha2
+ * @Nd A simple implementation of the SHA2 hashing functions.
+ * @Dd December 19 2022
+ * @Xr Memory Base64
+ *
+ * This API defines simple functions for computing SHA2 hashes.
+ * At the moment, it only defines
+ * .Fn Sha256 ,
+ * which computes the SHA-256 hash of the given C string. It is
+ * not trivial to implement SHA-512 in ANSI C due to the lack of
+ * a 64-bit integer type, so that hash function has been omitted.
+ */
+
+/**
+ * This function takes a pointer to a NULL-terminated C string, and
+ * returns a string allocated on the heap using the Memory API, or
+ * NULL if there was an error allocating memory. The returned string
+ * should be freed when it is no longer needed.
+ */
+extern char * Sha256(char *);
 
 #endif                             /* TELODENDRIA_SHA2_H */

tools/src/hdoc.c

@@ -398,8 +398,8 @@ last:
             {
                 StreamPuts(out, ", ");
             }
-            StreamPuts(out, ")\n");
         }
+        StreamPuts(out, ")\n");
 
         line = strtok(decl->docs, "\n");
         while (line)