Begin moving documentation to headers.

This commit is contained in:
Jordan Bancino 2023-04-27 03:08:39 +00:00
parent 3b06ab120b
commit 72467f6503
3 changed files with 141 additions and 27 deletions

View file

@ -25,45 +25,140 @@
#ifndef TELODENDRIA_ARRAY_H #ifndef TELODENDRIA_ARRAY_H
#define 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 <stddef.h>
#include <stdarg.h> #include <stdarg.h>
/**
* The functions in this API operate on an array structure which is
* opaque to the caller.
*/
typedef struct Array Array; 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 */ #endif /* TELODENDRIA_ARRAY_H */

View file

@ -25,7 +25,26 @@
#ifndef TELODENDRIA_SHA2_H #ifndef TELODENDRIA_SHA2_H
#define 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 */ #endif /* TELODENDRIA_SHA2_H */

View file

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