We do a little documentation

1 files changed, 125 insertions, 18 deletions

diff --git a/src/shared.h b/src/shared.h
index 3ff7b2d..6276281 100644
--- a/src/shared.h
+++ b/src/shared.h
@@ -1,28 +1,41 @@
+/**
+ * @file shared.h
+ * @author syxhe (https://t.me/syxhe)
+ * @brief A collection of functions and macros shared between files, or without a better place
+ * @version 0.1
+ * @date 2025-06-09
+ * 
+ * @copyright Copyright (c) 2025
+ * 
+ */
+
 #ifndef __VXGG_REWRITE___SHARED_H___3880294315821___
 #define __VXGG_REWRITE___SHARED_H___3880294315821___ 1
 
 #include <stddef.h>
 
-typedef int (*gcallback)(void*);    // Generic callback signature
-typedef void (*fcallback)(void*);   // free()-like callback signature
+typedef int (*gcallback)(void*);    //!< Generic callback signature
+typedef void (*fcallback)(void*);   //!< free()-like callback signature
 
+//! Get the size of a statically/vla defined array. Doesn't work on arrays allocated via `malloc()`
 #define STATIC_ARRAY_LEN(arr) (sizeof((arr))/sizeof((arr)[0]))
 
+//! Sets errno to `errval`, then returns `retval`. Defined as a macro because it is meant for use inside functions, not as a function itself
 #define ERRRET(errval, retval) do {\
     errno = (errval);\
     return (retval);\
 } while (0)
 
-// Defines how `x___alloc()` functions should exit. `___VXGG___XALLOC_EXIT_ON_ERROR___ > 0` calls `error()`, and thus functions
-// registered with `atexit()` and `on_exit()`. `___VXGG___XALLOC_EXIT_ON_ERROR___ <= 0` calls `abort()` on error. `x___alloc()` 
-// type functions will ALWAYS 'abort', doing otherwise defeats the purpose of the function type
+/// Defines how `x___alloc()` functions should exit. `___VXGG___XALLOC_EXIT_ON_ERROR___ > 0` calls `error()`, and thus functions
+/// registered with `atexit()` and `on_exit()`. `___VXGG___XALLOC_EXIT_ON_ERROR___ <= 0` calls `abort()` on error. `x___alloc()` 
+/// type functions will ALWAYS 'abort', doing otherwise defeats the purpose of the function type
 #define ___VXGG___XALLOC_EXIT_ON_ERROR___ 1
 
-// Defines whether vxgg functions that can error print out a short warning of the error when one is encountered. 
-// `___VXGG___VERBOSE_ERRORS___ > 0` will print diagnostic error messages, and will do nothing otherwise
+/// Defines whether vxgg functions that can error print out a short warning of the error when one is encountered. 
+/// `___VXGG___VERBOSE_ERRORS___ > 0` will print diagnostic error messages, and will do nothing otherwise
 #define ___VXGG___VERBOSE_ERRORS___ 1
 
-// Macro to exit on an alloc error instead of doing the terrible nested if statement that was being used previously
+//! Macro to exit on an alloc error instead of doing the terrible nested if statement that was being used previously
 #define XALLOC_EXIT(msg, ...) do {\
     if(!___VXGG___XALLOC_EXIT_ON_ERROR___)\
         abort();\
@@ -33,37 +46,122 @@ typedef void (*fcallback)(void*);   // free()-like callback signature
 } while (0)
 
 
+//! Holdover macro because I'm lazy. Used to call either malloc or xmalloc, but the xalloc functions were a bad idea, so I removed them
 #define VALLOC(nmemb, size) malloc((nmemb) * (size))
 
-// Error macro that gcc will not complain about
+//! Error macro that gcc will not complain about
 #define ERROR(status, errnum, format, ...) do {error((status), (errnum), (format)__VA_ARGS__); exit((status));} while (0)
-// Spit out a warning using `error`
+//! Spit out a warning using `error`
 #define WARN(errnum, format, ...) do {error(0, (errnum), (format)__VA_ARGS__);} while (0)
 
-// Read the entire contents of a file descriptor into a malloc()'ed buffer
+
+
+/**
+ * @brief Read the entire contents of a file descriptor into a malloc()'ed buffer
+ * 
+ * @param str Pointer to a string. Will be replaced with the malloc()'ed string
+ * @param initsize The initial size of the malloc()'ed string
+ * @param fd A file descriptor to read from
+ * @return int Returns the size of the array on success, or -1 on error
+ * @note The allocated buffer will expand and contract as necessary, but it's recommended to set `initsize` to some value close to or equal to the size of the file being read to reduce the number of resizes
+ */
 int rwbuf(char **str, unsigned long int initsize, int fd);
-// Write the entire contents of a buffer into a file descriptor
+
+/**
+ * @brief Write the entire contents of a buffer into a file descriptor
+ * 
+ * @param fd The file descriptor to write to
+ * @param buf The buffer to write from
+ * @param len The length of the buffer
+ * @return int Returns 0 on success, -1 on error
+ */
 int wwbuf(int fd, const unsigned char *buf, int len);
-// `dirname()` reimplementation that returns a malloc()'ed string
+
+
+
+/**
+ * @brief `dirname()` reimplementation that returns a malloc()'ed string
+ * 
+ * @param path The filepath to be inspected
+ * @return char* Returns a null-terminated string on success, or `null` on error
+ */
 char * vxdirname(const char * const path);
 
 
 
-// A locally defined structure designed for easier function cleanup
+/**
+ * @brief A locally defined structure designed for easier function cleanup
+ * 
+ */
 typedef struct cl {
-    fcallback *callbacks;   // Actual Type: fcallback callbacks[]
-    void * *arguments;      // Actual Type: void *arguments[]
-    int size;
-    int used;
+    fcallback *callbacks;   //!< An array of free()-like callbacks. Actual Type: fcallback callbacks[]
+    void * *arguments;      //!< An array of void pointers. Actual Type: void *arguments[]
+    int size;               //!< The size of each array
+    int used;               //!< The current number of used elements in each array
 } cleanup;
 
+/**
+ * @brief Initialize a cleanup object
+ * 
+ * @param loc The cleanup object to be initialized
+ * @param callbacks An array of free()-like callbacks. Must be `size` elements long
+ * @param arguments An array of void pointers. Must be `size` elements long
+ * @param size The number of elements the callbacks and arguments array are long
+ * @return int Returns 0 on success, -1 on error
+ */
 int cleanup_init(cleanup *loc, fcallback callbacks[], void *arguments[], int size);
+
+/**
+ * @brief Register a new callback and argument onto a cleanup stack
+ * 
+ * @param loc The cleanup object to modify
+ * @param cb A free()-like callback to run
+ * @param arg A piece of data for the callback to run
+ * @return int Returns 0 on success, -1 on error
+ */
 int cleanup_register(cleanup *loc, fcallback cb, void *arg);
+
+/**
+ * @brief Conditionally register a callback and argument
+ * 
+ * @param loc The cleanup object to modify
+ * @param cb A free()-like callback to run
+ * @param arg A piece of data for the callback to run
+ * @param flag Whether or not the register should take place. Will not run if `flag` is non-zero
+ * @return int Returns 0 on success or skip, -1 on error
+ */
 int cleanup_cndregister(cleanup *loc, fcallback cb, void *arg, unsigned char flag);
+
+/**
+ * @brief Clear a cleanup object
+ * @attention Does not free any registered callbacks or arguments, just marks them as available space
+ * 
+ * @param loc The cleanup object to modify
+ * @return int Returns 0 on success, -1 on error
+ */
 int cleanup_clear(cleanup *loc);
+
+/**
+ * @brief Fires all the registered callbacks and arguments in a cleanup object in FIFO (stack) order
+ * 
+ * @param loc The cleanup object to fire
+ * @return int Returns 0 on success, -1 on error
+ */
 int cleanup_fire(cleanup *loc);
+
+/**
+ * @brief Conditionally fires a cleanup object
+ * 
+ * @param loc The cleanup object in question
+ * @param flag Whether the object should be fired. Will skip firing if non-zero
+ * @return int Returns 0 on success, -1 on error
+ */
 int cleanup_cndfire(cleanup *loc, unsigned char flag);
 
+/**
+ * @brief Initializes a set of variables suitable for use in the cleanup macros
+ * @param size The number of elements long each array should be
+ */
 #define cleanup_CREATE(size) \
 cleanup __CLEANUP; \
 fcallback __CLEANUP_FUNCS[(size)]; \
@@ -71,14 +169,23 @@ void *__CLEANUP_ARGS[(size)]; \
 unsigned char __FLAG = 0; \
 cleanup_init(&__CLEANUP, __CLEANUP_FUNCS, __CLEANUP_ARGS, (size))
 
+//! Register a callback-argument pair using the local cleanup object
 #define cleanup_REGISTER(cb, arg)       cleanup_register(&__CLEANUP, (cb), (arg))
+//! Conditionally register a callback-argument pair using the local cleanup object
 #define cleanup_CNDREGISTER(cb, arg)    cleanup_cndregister(&__CLEANUP, (cb), (arg), __FLAG)
+//! Clean the local cleanup object
 #define cleanup_CLEAR()                 cleanup_clear(&__CLEANUP)
+//! Fire the local cleanup object
 #define cleanup_FIRE()                  cleanup_fire(&__CLEANUP)
+//! Conditionally fire the local cleanup object
 #define cleanup_CNDFIRE()               cleanup_cndfire(&__CLEANUP, __FLAG)
+//! Set the local cleanup flag to a non-zero number
 #define cleanup_MARK()                  (__FLAG = 1)
+//! Set the local cleanup flag to zero
 #define cleanup_UNMARK()                (__FLAG = 0)
+//! Check if the local cleanup flag is non-zero
 #define cleanup_ERRORFLAGGED            (__FLAG != 0)
+//! Conditionally execute some `code` if the local cleanup flag has not been marked
 #define cleanup_CNDEXEC(code)           while(!cleanup_ERRORFLAGGED) {code; break;}
 
 #endif
\ No newline at end of file