From 1f712c6e1bf9bd324c2954821c0188ab18439848 Mon Sep 17 00:00:00 2001
From: Ken Van Hoeylandt <git@kenvanhoeylandt.net>
Date: Tue, 14 Jan 2025 23:22:32 +0100
Subject: [PATCH] More TactilityC docs

---
 TactilityC/Source/tt_message_queue.cpp |  4 +++
 TactilityC/Source/tt_message_queue.h   | 38 ++++++++++++++++++++++++++
 TactilityC/Source/tt_mutex.h           | 26 ++++++++++++++++--
 3 files changed, 66 insertions(+), 2 deletions(-)

diff --git a/TactilityC/Source/tt_message_queue.cpp b/TactilityC/Source/tt_message_queue.cpp
index 80d2867f..95bd4ab9 100644
--- a/TactilityC/Source/tt_message_queue.cpp
+++ b/TactilityC/Source/tt_message_queue.cpp
@@ -33,6 +33,10 @@ uint32_t tt_message_queue_get_count(MessageQueueHandle handle) {
     return HANDLE_TO_MESSAGE_QUEUE(handle)->getCount();
 }
 
+uint32_t tt_message_queue_get_space(MessageQueueHandle handle) {
+    return HANDLE_TO_MESSAGE_QUEUE(handle)->getSpace();
+}
+
 bool tt_message_queue_reset(MessageQueueHandle handle) {
     return HANDLE_TO_MESSAGE_QUEUE(handle)->reset();
 }
diff --git a/TactilityC/Source/tt_message_queue.h b/TactilityC/Source/tt_message_queue.h
index 53f92841..d9bd3732 100644
--- a/TactilityC/Source/tt_message_queue.h
+++ b/TactilityC/Source/tt_message_queue.h
@@ -9,15 +9,53 @@ extern "C" {
 #include <stdint.h>
 #include <stdbool.h>
 
+/** A handle that represents a message queue instance */
 typedef void* MessageQueueHandle;
 
+/**
+ * Allocate a new message queue in memory.
+ * @param[in] capacity how many messages this queue can contain before it starts blocking input
+ * @param[in] messageSize the size of a message
+ */
 MessageQueueHandle tt_message_queue_alloc(uint32_t capacity, uint32_t messageSize);
+
+/** Free up the memory of a queue (dealloc) */
 void tt_message_queue_free(MessageQueueHandle handle);
+
+/**
+ * Put (post) a message in the queue
+ * @param[in] handle the queue handle
+ * @param[in] message the message of the correct size - its data will be copied
+ * @param[timeout] timeout the amount of ticks to wait until the message is queued
+ * @return true if the item was successfully queued
+ */
 bool tt_message_queue_put(MessageQueueHandle handle, const void* message, TickType_t timeout);
+
+/**
+ * Get the oldest message from the queue.
+ * @param[in] handle the queue handle
+ * @param[out] message a pointer to a message of the correct size
+ * @param[in] timeout the amount of ticks to wait until a message was copied
+ * @return true if a message was successfully copied
+ */
 bool tt_message_queue_get(MessageQueueHandle handle, void* message, TickType_t timeout);
+
+/** @return the total amount of messages that this queue can hold */
 uint32_t tt_message_queue_get_capacity(MessageQueueHandle handle);
+
+/** @return the size of a single message in the queue */
 uint32_t tt_message_queue_get_message_size(MessageQueueHandle handle);
+
+/** @return the current amount of items in the queue */
 uint32_t tt_message_queue_get_count(MessageQueueHandle handle);
+
+/** @return the remaining capacity in the queue */
+uint32_t tt_message_queue_get_space(MessageQueueHandle handle);
+
+/**
+ * Remove all items from the queue (if any)
+ * @return true on failure
+ */
 bool tt_message_queue_reset(MessageQueueHandle handle);
 
 #ifdef __cplusplus
diff --git a/TactilityC/Source/tt_mutex.h b/TactilityC/Source/tt_mutex.h
index 8f4b8e4e..f3ba3ddf 100644
--- a/TactilityC/Source/tt_mutex.h
+++ b/TactilityC/Source/tt_mutex.h
@@ -9,6 +9,7 @@ extern "C" {
 #include <stdint.h>
 #include <stdbool.h>
 
+/** A handle that represents a mutex instance */
 typedef void* MutexHandle;
 
 enum TtMutexType {
@@ -16,9 +17,30 @@ enum TtMutexType {
     MUTEX_TYPE_RECURSIVE
 };
 
-MutexHandle tt_mutex_alloc(enum TtMutexType);
+/**
+ * Allocate a new mutex instance
+ * @param[in] type specify if the mutex is either a normal one, or whether it can recursively (re)lock
+ * @return the allocated instance
+ */
+MutexHandle tt_mutex_alloc(enum TtMutexType type);
+
+/** Free up the memory of the specified mutex instance. */
 void tt_mutex_free(MutexHandle handle);
-bool tt_mutex_lock(MutexHandle handle, TickType_t timeoutTicks);
+
+/**
+ * Attempt to lock a mutex.
+ * @param[in] handle the handle that represents the mutex instance
+ * @param[in] timeout the maximum amount of ticks to wait when trying to lock
+ * @return true when the lock was acquired
+ */
+bool tt_mutex_lock(MutexHandle handle, TickType_t timeout);
+
+/**
+ * Attempt to unlock a mutex.
+ * @param[in] handle the handle that represents the mutex instance
+ * @param[in] timeout the maximum amount of ticks to wait when trying to unlock
+ * @return true when the lock was unlocked
+ */
 bool tt_mutex_unlock(MutexHandle handle);
 
 #ifdef __cplusplus