core: add documentation comments to API functions

Add documentation comments to the functions and structures exposed
through the Rune API.

Signed-off-by: Danny Holman <dholman@gymli.org>

8 files changed, 220 insertions, 32 deletions

diff --git a/include/rune/core/abort.h b/include/rune/core/abort.h
index 60f368e..5356c5d 100644
--- a/include/rune/core/abort.h
+++ b/include/rune/core/abort.h
@@ -24,6 +24,10 @@
 
 #include <rune/util/types.h>
 
+/**
+ * \brief Called during a fatal error, force-quits the engine,
+ * calls a stack trace on POSIX-compliant platforms
+ */
 RAPI void rune_abort(void);
 
 #endif
diff --git a/include/rune/core/alloc.h b/include/rune/core/alloc.h
index 35170d8..65121ce 100644
--- a/include/rune/core/alloc.h
+++ b/include/rune/core/alloc.h
@@ -25,6 +25,9 @@
 #include <rune/util/types.h>
 #include <rune/util/list.h>
 
+/**
+ * Memory block used for memory accounting
+ */
 struct mem_block {
         void *ptr;
         size_t sz;
@@ -32,10 +35,40 @@ struct mem_block {
         struct list_head list;
 };
 
+/**
+ * \brief Custom malloc implementation
+ * \param[in] sz The size of the requested memory block
+ * \return A pointer to void, or NULL in case of error
+ */
 RAPI void* rune_alloc(size_t sz);
+
+/**
+ * \brief Custom calloc implementation
+ * \param[in] nmemb An integer to fill the memory block with
+ * \param[in] sz The size of the requested memory block
+ * \return A pointer to void, or NULL in case of error
+ */
 RAPI void* rune_calloc(size_t nmemb, size_t sz);
+
+/**
+ * \brief Custom realloc implementation
+ * \param[in] ptr A void pointer to a previously alloc'd block, or NULL
+ * \param[in] sz The size of the requested memory block
+ * \return A pointer to void, or NULL in case of error
+ */
 RAPI void* rune_realloc(void *ptr, size_t sz);
+
+/**
+ * \brief Custom free implementation
+ * \param[in] ptr A void pointer to a previously alloc'd block
+ */
 RAPI void rune_free(void *ptr);
+
+/**
+ * \brief Used to free all memory currently in use by the engine
+ * This function should only be used at the end of execution, and is normally
+ * called by rune_exit.
+ */
 RAPI void rune_free_all(void);
 
 #endif
diff --git a/include/rune/core/init.h b/include/rune/core/init.h
index 3aef63c..50f7188 100644
--- a/include/rune/core/init.h
+++ b/include/rune/core/init.h
@@ -19,12 +19,28 @@
  * 3. This notice may not be removed or altered from any source distribution.
  */
 
-#ifndef RUNE_INIT_H
-#define RUNE_INIT_H
+#ifndef RUNE_CORE_INIT_H
+#define RUNE_CORE_INIT_H
 
 #include <rune/util/types.h>
 
-RAPI struct rune_window* rune_init(uint32_t width, uint32_t height, const char *title);
+/**
+ * \brief Main point of initialization, must be called before any other engine
+ * function
+ * \param[in] argc The same argc defined in the program's main function
+ * \param[in] argv The same argv defined in the program's main function
+ * \return 0, or a negative number indicating the error
+ */
+RAPI int rune_init(int argc, char* argv[]);
+
+/**
+ * \brief Shuts down the engine and cleans up any remaining memory
+ */
 RAPI void rune_exit(void);
 
+/**
+ * \brief Hot-reloads the entire engine library from disk
+ */
+RAPI int rune_hot_reload(void);
+
 #endif
diff --git a/include/rune/core/logging.h b/include/rune/core/logging.h
index df4ed7e..5582d0d 100644
--- a/include/rune/core/logging.h
+++ b/include/rune/core/logging.h
@@ -24,18 +24,41 @@
 
 #include <rune/util/types.h>
 
+/// Indicates the error level of the message
 enum log_level {
-        LOG_FATAL,
-        LOG_ERROR,
-        LOG_WARN,
-        LOG_INFO,
-        LOG_DEBUG
+        LOG_FATAL,      ///< A major error has occured and execution cannot continue
+        LOG_ERROR,      ///< A major error has occured
+        LOG_WARN,       ///< A minor error has occured
+        LOG_INFO,       ///< A simple event has occured
+        LOG_DEBUG       ///< A confirmation or other debugging message, only printed when enabled
 };
 
+/**
+ * \brief Print message to the engine log
+ * \param[in] level Error level, a value in log_level
+ * \param[in] fmt Format string
+ * \param[in] ... Format specifiers (%d, %s, etc.)
+ */
 RAPI void log_output(int level, const char *fmt, ...);
+
+/**
+ * \brief Enable debug logging
+ */
 RAPI void enable_log_debug(void);
+
+/**
+ * \brief Disable debug logging (default)
+ */
 RAPI void disable_log_debug(void);
+
+/**
+ * \brief Enable color output (default)
+ */
 RAPI void enable_log_color(void);
+
+/**
+ * \brief Disable color output
+ */
 RAPI void disable_log_color(void);
 
 #endif
diff --git a/include/rune/core/mod.h b/include/rune/core/mod.h
index 8c63d5f..f0940ce 100644
--- a/include/rune/core/mod.h
+++ b/include/rune/core/mod.h
@@ -47,19 +47,44 @@
 
 #endif
 
+/// Function pointer, used by the mod struct
 typedef void (*mod_func)(void);
 
+/**
+ * Class-like definition for in-game mod
+ */
 struct mod {
-        const char *name;
-        mod_func init_func;
-        mod_func exit_func;
-        mod_func update_func;
-        struct list_head list;
+        const char *name;       ///< Name of the mod
+        mod_func init_func;     ///< Mod initialization function, called by rune_init_mods
+        mod_func exit_func;     ///< Mod exit function, called by rune_close_mods
+        mod_func update_func;   ///< Mod update function, called at every frame
+        struct list_head list;  ///< Linked list of all mod structs, used internally
 };
 
+/**
+ * \brief Load all the mods from the mod folder, mods must be either DLLs on Windows,
+ * or shared objects on Linux.
+ */
 RAPI void rune_load_mods(void);
+
+/**
+ * \brief Iterate over the list of mods and call each mod's init_func
+ */
 RAPI void rune_init_mods(void);
+
+/**
+ * \brief Iterate over the list of mods, call each mod's exit_func and release memory
+ */
 RAPI void rune_close_mods(void);
+
+/**
+ * \brief Mod registration function, called by a mod by way of the REGISTER_MOD
+ * macro
+ * \param[in] name Name of the mod (can include version information)
+ * \param[in] init_func Mod init function, called by rune_init_mods
+ * \param[in] exit_func Mod exit function, called by rune_exit_mods
+ * \param[in] update_func Mod update function, called during each frame
+ */
 RAPI void rune_register_mod(const char *name, mod_func init_func, mod_func exit_func, mod_func update_func);
 
 #endif
diff --git a/include/rune/core/thread.h b/include/rune/core/thread.h
index 698136c..976b7d3 100644
--- a/include/rune/core/thread.h
+++ b/include/rune/core/thread.h
@@ -25,30 +25,88 @@
 #include <rune/util/types.h>
 #include <rune/util/list.h>
 
+/**
+ * Platform-agnostic thread handle
+ */
 struct thread {
-        int ID;
-        int detached;
-        void *thread_handle;
-        struct list_head list;
+        int ID;                 ///< In-engine thread ID
+        int detached;           ///< 1 if thread has been detached, 0 otherwise
+        void *thread_handle;    ///< System-defined thread handle, usually a pthread_t
+        struct list_head list;  ///< Linked list of all threads, used internally
 };
 
+/**
+ * Platform-agnostic mutex handle
+ */
 struct mutex {
-        int ID;
-        void *mutex_handle;
-        struct list_head list;
+        int ID;                 ///< In-engine mutex ID
+        void *mutex_handle;     ///< System-defined mutex handle, usually a pthread_mutex_t
+        struct list_head list;  ///< Linked list of all mutexes, used internally
 };
 
+/**
+ * \brief Initializes the engine's thread API, must be called before using any
+ * API function
+ */
 RAPI void rune_init_thread_api(void);
 
+/**
+ * \brief Creates and starts a new thread
+ * \param[in] thread_fn The function the thread will execute
+ * \param[in] data Arguments for the thread_fn
+ * \param[in] detached Whether the thread will start detached
+ * \return ID of created thread, or -1 if error
+ */
 RAPI int rune_thread_init(void* (*thread_fn)(void *data), void *data, int detached);
+
+/**
+ * \brief Force-stops a thread
+ * \param[in] ID Thread to stop
+ * \return 0, or -1 if thread cannot be found
+ */
 RAPI int rune_thread_cancel(int ID);
+
+/**
+ * \brief Joins a thread to the calling thread
+ * \param[in] ID Thread to wait on
+ * \param[out] retval Return value of thread_fn
+ */
 RAPI int rune_thread_join(int ID, void **retval);
+
+/**
+ * \brief Gets the current thread ID
+ * \return Current in-engine ID of the calling thread, or -1 on error
+ */
 RAPI int rune_thread_self(void);
+
+/**
+ * \brief Terminates the calling thread
+ * \param[in] retval Where to put the thread_fn return value
+ */
 RAPI void rune_thread_exit(void *retval);
 
+/**
+ * \brief Creates a new mutex
+ * \return ID of new mutex, or -1 on error
+ */
 RAPI int rune_mutex_init(void);
+
+/**
+ * \brief Cleans up a mutex and releases its memory
+ * \param[in] ID Mutex to destroy
+ */
 RAPI int rune_mutex_destroy(int ID);
+
+/**
+ * \brief Locks a mutex
+ * \param[in] ID Mutex to lock
+ */
 RAPI int rune_mutex_lock(int ID);
+
+/**
+ * \brief Unlocks a mutex
+ * \param[in] ID Mutex to unlock
+ */
 RAPI int rune_mutex_unlock(int ID);
 
 #endif
diff --git a/include/rune/util/list.h b/include/rune/util/list.h
index ed6db5e..556e085 100644
--- a/include/rune/util/list.h
+++ b/include/rune/util/list.h
@@ -24,12 +24,20 @@
 
 #include <stddef.h>
 
-RAPI struct list_head {
-        struct list_head *next;
-        struct list_head *prev;
+/**
+ * Linux-kernel combatible linked list implementation
+ */
+struct list_head {
+        struct list_head *next; ///< Next list element
+        struct list_head *prev; ///< Previous list element
 };
 
-RAPI static inline void list_add(struct list_head *new, struct list_head *head) {
+/**
+ * \brief Add element to the end of a list
+ * \param[in] new Pointer to struct list_head, part of another struct
+ * \param[in] head Start point of the list to be added to
+ */
+static inline void list_add(struct list_head *new, struct list_head *head) {
         struct list_head *temp = head;
         while (temp->next != NULL)
                 temp = temp->next;
@@ -39,7 +47,11 @@ RAPI static inline void list_add(struct list_head *new, struct list_head *head)
         new->next = NULL;
 }
 
-RAPI static inline void list_del(struct list_head *item) {
+/**
+ * \brief Remove element from a list
+ * \param[in] item Pointer to struct list_head, part of another struct
+ */
+static inline void list_del(struct list_head *item) {
         struct list_head *next = item->next;
         struct list_head *prev = item->prev;
         if (next != NULL)
diff --git a/include/rune/util/util.h b/include/rune/util/util.h
index dcf45e4..1ba6781 100644
--- a/include/rune/util/util.h
+++ b/include/rune/util/util.h
@@ -23,32 +23,49 @@
 #define RUNE_UTIL_UTIL_H
 
 #include <assert.h>
+#include <stddef.h>
 #include <stdint.h>
 
+/// Use the compiler-specific version of static_assert
 #if defined(__clang__) || defined(__gcc__)
         #define STATIC_ASSERT _Static_assert
 #else
         #define STATIC_ASSERT static_assert
 #endif
 
+/// GLFW requires this to enable dynamic linking on Windows
+#if _WIN32
+#define GLFW_DLL 1
+#endif
 
-#ifdef REXPORT
-        #ifdef _MSC_VER
+/// Make API functions visible outside of the library
+#ifdef RAPI_EXPORT
+        #ifdef _WIN32
                 #define RAPI __declspec(dllexport)
         #else
                 #define RAPI __attribute__((visibility("default")))
         #endif
 #else
-        #ifdef _MSC_VER
-                #define RAPI __declspec(dllexport)
+        #ifdef _WIN32
+                #define RAPI __declspec(dllimport)
         #else
                 #define RAPI
         #endif
 #endif
 
-static inline uint32_t clamp(uint32_t value, float min, float max) {
-        const uint32_t ret = value < min ? min : value;
-        return ret > max ? max : ret;
+/**
+ * \brief Clamps a value between two floating point values
+ * \param[in] x Value to be clamped
+ * \param[in] min Floor value
+ * \param[in] max Ceiling value
+ * \return One of min, max or x
+ */
+static inline float clamp(float x, float min, float max) {
+        if (x < min)
+                return min;
+        if (x > max)
+                return max;
+        return x;
 }
 
 #endif