Merge develop into main (#167)

- WiFi Connect app is now hidden by default, but accessible at the bottom of the WiFi Manage app when WiFi is turned on.
- WiFi service now turns on WiFi when calling connect() and WiFi is not on.
- Removed `blocking` option for `service::loader::startApp()`. This feature was unused and complex.
- Various apps: Moved private headers into Private/ folder.
- Various apps: created start() function for easy starting.
- Added documentation to all TactilityC APIs
- Refactored various `enum` into `class enum`
- Refactor M5Stack `initBoot()` (but VBus is still 0V for some reason)

TactilityC/Source/tt_app_alertdialog.cpp

@@ -6,8 +6,7 @@ extern "C" {
 void tt_app_alertdialog_start(const char* title, const char* message, const char* buttonLabels[], uint32_t buttonLabelCount) {
     std::vector<std::string> list;
     for (int i = 0; i < buttonLabelCount; i++) {
-        const char* item = buttonLabels[i];
-        list.push_back(item);
+        list.emplace_back(buttonLabels[i]);
     }
     tt::app::alertdialog::start(title, message, list);
 }

TactilityC/Source/tt_app_alertdialog.h

@@ -8,7 +8,18 @@ extern "C" {
 
 #include <stdint.h>
 
+/**
+ * Show a dialog with the provided title, message and 0, 1 or more buttons.
+ * @param[in] title the title to show in the toolbar
+ * @param[in] message the message to display
+ * @param[in] buttonLabels the buttons to show, or null when there are none to show
+ * @param[in] buttonLabelCount the amount of buttons (0 or more)
+ */
 void tt_app_alertdialog_start(const char* title, const char* message, const char* buttonLabels[], uint32_t buttonLabelCount);
+
+/**
+ * @return the index of the button that was clicked (the index in the array when start() was called)
+ */
 int32_t tt_app_alertdialog_get_result_index(BundleHandle handle);
 
 #ifdef __cplusplus

TactilityC/Source/tt_app_context.h

@@ -8,10 +8,30 @@ extern "C" {
 
 typedef void* AppContextHandle;
 
+/** @return the data that was attached to this app context */
 void* _Nullable tt_app_context_get_data(AppContextHandle handle);
+
+/**
+ * Attach data to an application context.
+ * Don't forget to manually delete allocated memory when onStopped() is called.
+ * @param[in] handle the app context handle
+ * @param[in] data the data to attach
+ */
 void tt_app_context_set_data(AppContextHandle handle, void* _Nullable data);
+
+/** @return the bundle that belongs to this application, or null */
 BundleHandle _Nullable tt_app_context_get_parameters(AppContextHandle handle);
+
+/**
+ * Set the result before closing an app.
+ * The result and bundle are passed along to the app that launched this app, when this app is closed.
+ * @param[in] handle the app context handle to set the result for
+ * @param[in] result the result state to set
+ * @param[in] bundle the result bundle to set
+ */
 void tt_app_context_set_result(AppContextHandle handle, Result result, BundleHandle _Nullable bundle);
+
+/** @return true if a result was set for this app context */
 bool tt_app_context_has_result(AppContextHandle handle);
 
 #ifdef __cplusplus

TactilityC/Source/tt_app_manifest.h

@@ -21,6 +21,16 @@ typedef void (*AppOnShow)(AppContextHandle app, lv_obj_t* parent);
 typedef void (*AppOnHide)(AppContextHandle app);
 typedef void (*AppOnResult)(AppContextHandle app, Result result, BundleHandle resultData);
 
+/**
+ * This is used to register the manifest of an external app.
+ * @param[in] name the application's human-readable name
+ * @param[in] icon the optional application icon (you can use LV_SYMBOL_* too)
+ * @param[in] onStart called when the app is launched (started)
+ * @param[in] onStop called when the app is exited (stopped)
+ * @param[in] onShow called when the app is about to be shown to the user (app becomes visible)
+ * @param[in] onHide called when the app is about to be invisible to the user (e.g. other app was launched by this app, and this app goes to the background)
+ * @param[in] onResult called when the app receives a result after launching another app
+ */
 void tt_set_app_manifest(
     const char* name,
     const char* _Nullable icon,

TactilityC/Source/tt_app_selectiondialog.cpp

@@ -6,8 +6,7 @@ extern "C" {
 void tt_app_selectiondialog_start(const char* title, int argc, const char* argv[]) {
     std::vector<std::string> list;
     for (int i = 0; i < argc; i++) {
-        const char* item = argv[i];
-        list.push_back(item);
+        list.emplace_back(argv[i]);
     }
     tt::app::selectiondialog::start(title, list);
 }

TactilityC/Source/tt_app_selectiondialog.h

@@ -6,8 +6,15 @@
 extern "C" {
 #endif
 
+/**
+ * Start an app that displays a list of items and allows the user to select one.
+ * @param[in] title the title to show in the toolbar
+ * @param[in] argc the amount of items that the list contains
+ * @param[in] argv the labels of the items in the list
+ */
 void tt_app_selectiondialog_start(const char* title, int argc, const char* argv[]);
 
+/** @return the index of the item that was clicked by the user, or -1 when the user didn't select anything */
 int32_t tt_app_selectiondialog_get_result_index(BundleHandle handle);
 
 #ifdef __cplusplus

TactilityC/Source/tt_bundle.h

@@ -7,21 +7,66 @@ extern "C" {
 #include <stdint.h>
 #include <stdbool.h>
 
+/** The handle that represents a bundle instance */
 typedef void* BundleHandle;
 
+/** @return a new bundle instance */
 BundleHandle tt_bundle_alloc();
+
+/** Dealloc an existing bundle instance */
 void tt_bundle_free(BundleHandle handle);
 
-bool tt_bundle_opt_bool(BundleHandle handle, const char* key, bool* out);
-bool tt_bundle_opt_int32(BundleHandle handle, const char* key, int32_t* out);
 /**
- * Note that outSize must be large enough to include null terminator.
- * This means that your string has to be the expected text length + 1 extra character.
+ * Try to get a boolean value from a Bundle
+ * @param[in] handle the handle that represents the bundle
+ * @param[in] key the identifier that represents the stored value (~variable name)
+ * @param[out] out the output value (only set when return value is set to true)
+ * @return true if "out" was set
+ */
+bool tt_bundle_opt_bool(BundleHandle handle, const char* key, bool* out);
+
+/**
+ * Try to get an int32_t value from a Bundle
+ * @param[in] handle the handle that represents the bundle
+ * @param[in] key the identifier that represents the stored value (~variable name)
+ * @param[out] out the output value (only set when return value is set to true)
+ * @return true if "out" was set
+ */
+bool tt_bundle_opt_int32(BundleHandle handle, const char* key, int32_t* out);
+
+/**
+ * Try to get a string from a Bundle
+ * @warning outSize must be large enough to include null terminator. This means that your string has to be the expected text length + 1 extra character.
+ * @param[in] handle the handle that represents the bundle
+ * @param[in] key the identifier that represents the stored value (~variable name)
+ * @param[out] out the buffer to store the string in
+ * @param[in] outSize the size of the buffer
+ * @return true if "out" was set
  */
 bool tt_bundle_opt_string(BundleHandle handle, const char* key, char* out, uint32_t outSize);
 
+/**
+ * Store a boolean value in a Bundle
+ * @param[in] handle the handle that represents the bundle
+ * @param[in] key the identifier that represents the stored value (~variable name)
+ * @param[in] value the value to store
+ */
 void tt_bundle_put_bool(BundleHandle handle, const char* key, bool value);
+
+/**
+ * Store an int32_t value in a Bundle
+ * @param[in] handle the handle that represents the bundle
+ * @param[in] key the identifier that represents the stored value (~variable name)
+ * @param[in] value the value to store
+ */
 void tt_bundle_put_int32(BundleHandle handle, const char* key, int32_t value);
+
+/**
+ * Store a string value in a Bundle
+ * @param[in] handle the handle that represents the bundle
+ * @param[in] key the identifier that represents the stored value (~variable name)
+ * @param[in] value the value to store
+ */
 void tt_bundle_put_string(BundleHandle handle, const char* key, const char* value);
 
 #ifdef __cplusplus

TactilityC/Source/tt_hal_i2c.cpp

@@ -20,15 +20,15 @@ bool tt_hal_i2c_master_read(i2c_port_t port, uint8_t address, uint8_t* data, siz
 }
 
 bool tt_hal_i2c_master_read_register(i2c_port_t port, uint8_t address, uint8_t reg, uint8_t* data, size_t dataSize, TickType_t timeout) {
-    return tt::hal::i2c::masterRead(port, address, reg, data, dataSize, timeout);
+    return tt::hal::i2c::masterReadRegister(port, address, reg, data, dataSize, timeout);
 }
 
-bool tt_hal_i2c_master_write(i2c_port_t port, uint16_t address, const uint8_t* data, uint16_t dataSize, TickType_t timeout) {
+bool tt_hal_i2c_master_write(i2c_port_t port, uint8_t address, const uint8_t* data, uint16_t dataSize, TickType_t timeout) {
     return tt::hal::i2c::masterWrite(port, address, data, dataSize, timeout);
 }
 
-bool tt_hal_i2c_master_write_register(i2c_port_t port, uint16_t address, uint8_t reg, const uint8_t* data, uint16_t dataSize, TickType_t timeout) {
-    return tt::hal::i2c::masterWrite(port, address, reg, data, dataSize, timeout);
+bool tt_hal_i2c_master_write_register(i2c_port_t port, uint8_t address, uint8_t reg, const uint8_t* data, uint16_t dataSize, TickType_t timeout) {
+    return tt::hal::i2c::masterWriteRegister(port, address, reg, data, dataSize, timeout);
 }
 
 bool tt_hal_i2c_master_write_read(i2c_port_t port, uint8_t address, const uint8_t* writeData, size_t writeDataSize, uint8_t* readData, size_t readDataSize, TickType_t timeout) {

TactilityC/Source/tt_hal_i2c.h

@@ -8,18 +8,102 @@
 extern "C" {
 #endif
 
+/**
+ * Start I2C communications for the specified port
+ * @param[in] port the I2C port to init
+ * @return true on success
+ */
 bool tt_hal_i2c_start(i2c_port_t port);
+
+/**
+ * Stop I2C communications for the specified port
+ * @param[in] port the I2C port to deinit
+ * @return true on success
+ */
 bool tt_hal_i2c_stop(i2c_port_t port);
+
+/**
+ * Check if the port was successfully started.
+ * @param[in] port the port to check
+ * @return true when the port was successfully started
+ */
 bool tt_hal_i2c_is_started(i2c_port_t port);
 
+/**
+ * Read from an I2C port in master mode.
+ * @param[in] port the I2C port to read from
+ * @param[in] address
+ * @param[in] data
+ * @param[in] dataSize
+ * @param[in] timeout
+ */
 bool tt_hal_i2c_master_read(i2c_port_t port, uint8_t address, uint8_t* data, size_t dataSize, TickType_t timeout);
+
+/**
+ * Read a register from an I2C port in master mode.
+ * @param[in] port the I2C port to read from
+ * @param[in] address
+ * @param[in] reg
+ * @param[in] data
+ * @param[in] dataSize
+ * @param[in] timeout
+ */
 bool tt_hal_i2c_master_read_register(i2c_port_t port, uint8_t address, uint8_t reg, uint8_t* data, size_t dataSize, TickType_t timeout);
-bool tt_hal_i2c_master_write(i2c_port_t port, uint16_t address, const uint8_t* data, uint16_t dataSize, TickType_t timeout);
-bool tt_hal_i2c_master_write_register(i2c_port_t port, uint16_t address, uint8_t reg, const uint8_t* data, uint16_t dataSize, TickType_t timeout);
+
+/**
+ * Write to an I2C port in master mode.
+ * @param[in] port the I2C port to write to
+ * @param[in] address
+ * @param[in] data
+ * @param[in] dataSize
+ * @param[in] timeout
+ */
+bool tt_hal_i2c_master_write(i2c_port_t port, uint8_t address, const uint8_t* data, uint16_t dataSize, TickType_t timeout);
+
+/**
+ * Write to a register of an I2C port in master mode.
+ * @param[in] port the I2C port to write to
+ * @param[in] address
+ * @param[in] reg
+ * @param[in] data
+ * @param[in] dataSize
+ * @param[in] timeout
+ */
+bool tt_hal_i2c_master_write_register(i2c_port_t port, uint8_t address, uint8_t reg, const uint8_t* data, uint16_t dataSize, TickType_t timeout);
+
+/**
+ * Write then read from an I2C port in master mode.
+ * @param[in] port the I2C port to communicate with
+ * @param[in] address
+ * @param[in] writeData
+ * @param[in] writeDataSize
+ * @param[in] readData
+ * @param[in] readDataSize
+ * @param[in] timeout
+ */
 bool tt_hal_i2c_master_write_read(i2c_port_t port, uint8_t address, const uint8_t* writeData, size_t writeDataSize, uint8_t* readData, size_t readDataSize, TickType_t timeout);
+
+/**
+ * Check if an I2C port has a device at the specified address.
+ * @param[in] port the I2C port to communicate with
+ * @param[in] address
+ * @param[in] timeout
+ */
 bool tt_hal_i2c_master_has_device_at_address(i2c_port_t port, uint8_t address, TickType_t timeout);
 
+/**
+ * Used to lock an I2C port.
+ * This is useful for creating thread-safe I2C calls while calling ESP-IDF directly of third party I2C APIs.
+ * @param[in] port the I2C port to lock
+ * @param[in] timeout
+ */
 bool tt_hal_i2c_lock(i2c_port_t port, TickType_t timeout);
+
+/**
+ * Used to unlock an I2C port.
+ * This is useful for creating thread-safe I2C calls while calling ESP-IDF directly of third party I2C APIs.
+ * @param[in] port the I2C port to unlock
+ */
 bool tt_hal_i2c_unlock(i2c_port_t port);
 
 #ifdef __cplusplus

TactilityC/Source/tt_init.h

@@ -4,6 +4,10 @@
 extern "C" {
 #endif
 
+/**
+ * Initialization method for TactilityC
+ * @warning This is called from the main firmware. Don't call this from an external app!
+ */
 void tt_init_tactility_c();
 
 #ifdef __cplusplus

TactilityC/Source/tt_lvgl_spinner.h

@@ -6,6 +6,7 @@
 extern "C" {
 #endif
 
+/** Create a spinner widget. */
 lv_obj_t* tt_lvgl_spinner_create(lv_obj_t* parent);
 
 #ifdef __cplusplus

TactilityC/Source/tt_lvgl_toolbar.h

@@ -7,7 +7,10 @@
 extern "C" {
 #endif
 
+/** Create a toolbar widget that shows the app name as title */
 lv_obj_t* tt_lvgl_toolbar_create(lv_obj_t* parent, AppContextHandle context);
+
+/** Create a toolbar widget with the provided title*/
 lv_obj_t* tt_lvgl_toolbar_create_simple(lv_obj_t* parent, const char* title);
 
 #ifdef __cplusplus

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();
 }

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

TactilityC/Source/tt_mutex.cpp

@@ -8,9 +8,9 @@ extern "C" {
 MutexHandle tt_mutex_alloc(enum TtMutexType type) {
     switch (type) {
         case TtMutexType::MUTEX_TYPE_NORMAL:
-            return new tt::Mutex(tt::Mutex::TypeNormal);
+            return new tt::Mutex(tt::Mutex::Type::Normal);
         case TtMutexType::MUTEX_TYPE_RECURSIVE:
-            return new tt::Mutex(tt::Mutex::TypeRecursive);
+            return new tt::Mutex(tt::Mutex::Type::Recursive);
         default:
             tt_crash("Type not supported");
     }

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

TactilityC/Source/tt_semaphore.h

@@ -9,12 +9,40 @@ extern "C" {
 #include <stdint.h>
 #include <stdbool.h>
 
+/** A handle that represents a semaphore instance */
 typedef void* SemaphoreHandle;
 
+/**
+ * Allocate a new semaphore instance.
+ * @param[in] maxCount the maximum counter value
+ * @param[in] initialCount the initial counter value
+ * @return the handle that represents the new instance
+ */
 SemaphoreHandle tt_semaphore_alloc(uint32_t maxCount, TickType_t initialCount);
+
+/** Free up the memory of a specified semaphore instance */
 void tt_semaphore_free(SemaphoreHandle handle);
-bool tt_semaphore_acquire(SemaphoreHandle handle, TickType_t timeoutTicks);
+
+/**
+ * Attempt to acquire a semaphore (increase counter)
+ * @param[in] handle the instance handle
+ * @param[in] timeout the maximum amount of ticks to wait while trying to acquire
+ * @return true on successfully acquiring the semaphore (counter is increased)
+ */
+bool tt_semaphore_acquire(SemaphoreHandle handle, TickType_t timeout);
+
+/**
+ * Release an acquired semaphore (decrease counter)
+ * @param[in] handle the instance handle
+ * @return true on successfully releasing the semaphore (counter is decreased)
+ */
 bool tt_semaphore_release(SemaphoreHandle handle);
+
+/**
+ * Get the counter value of this semaphore instance
+ * @param[in] handle the instance handle
+ * @return the current counter value (acquisition count)
+ */
 uint32_t tt_semaphore_get_count(SemaphoreHandle handle);
 
 #ifdef __cplusplus

TactilityC/Source/tt_service_loader.cpp

@@ -4,9 +4,9 @@
 
 extern "C" {
 
-void tt_service_loader_start_app(const char* id, bool blocking, BundleHandle _Nullable bundle) {
+void tt_service_loader_start_app(const char* id, BundleHandle _Nullable bundle) {
     auto shared_bundle = std::shared_ptr<tt::Bundle>((tt::Bundle*)bundle);
-    tt::service::loader::startApp(id, blocking, std::move(shared_bundle));
+    tt::service::loader::startApp(id, std::move(shared_bundle));
 }
 
 void tt_service_loader_stop_app() {

TactilityC/Source/tt_service_loader.h

@@ -8,12 +8,24 @@ extern "C" {
 #endif
 
 /**
+ * Start an application providing a manifest id and an optional bundle.
+ * Execution is always deferred.
+ * This function generally returns immediately unless the scheduler is blocked.
  * @param[in] id application manifest id
- * @param[in] blocking whether this operation blocks until the application is started
  * @param[in] bundle an allocated bundle (or NULL) of which the memory ownership is handed over to this function
  */
-void tt_service_loader_start_app(const char* id, bool blocking, BundleHandle _Nullable bundle);
+void tt_service_loader_start_app(const char* id, BundleHandle _Nullable bundle);
+
+/**
+ * Stop the currently active app.
+ * Execution is always deferred.
+ * This function generally returns immediately unless the scheduler is blocked.
+ */
 void tt_service_loader_stop_app();
+
+/**
+ * Get the context handle of the app that is currently shown on the screen.
+ */
 AppContextHandle tt_service_loader_get_current_app();
 
 #ifdef __cplusplus

TactilityC/Source/tt_thread.cpp

@@ -55,8 +55,8 @@ void tt_thread_start(ThreadHandle handle) {
     HANDLE_AS_THREAD(handle)->start();
 }
 
-bool tt_thread_join(ThreadHandle handle) {
-    return HANDLE_AS_THREAD(handle)->join();
+bool tt_thread_join(ThreadHandle handle, TickType_t timeout) {
+    return HANDLE_AS_THREAD(handle)->join(timeout);
 }
 
 ThreadId tt_thread_get_id(ThreadHandle handle) {

TactilityC/Source/tt_thread.h

@@ -16,14 +16,17 @@ extern "C" {
 #include <stdbool.h>
 #include <stddef.h>
 
+/** The handle that represents the thread insance */
 typedef void* ThreadHandle;
 
+/** The state of a thread instance */
 typedef enum {
     ThreadStateStopped,
     ThreadStateStarting,
     ThreadStateRunning,
 } ThreadState;
 
+/** The identifier that represents the thread */
 typedef TaskHandle_t ThreadId;
 
 /** ThreadCallback Your callback to run in new thread
@@ -48,23 +51,98 @@ typedef enum {
     ThreadPriorityHighest = 7U
 } ThreadPriority;
 
+/** @return a thread handle that represents a newly allocated thread instance */
 ThreadHandle tt_thread_alloc();
+
+/**
+ * Allocate a thread and provide some common parameters so it's all ready to be started.
+ * @param[in] name the name of the thread
+ * @param[in] stackSize the size of the stack in bytes
+ * @param[in] callback the callback to call from the thread
+ * @param[in] callbackContext the data to pass to the callback
+ */
 ThreadHandle tt_thread_alloc_ext(
     const char* name,
     uint32_t stackSize,
     ThreadCallback callback,
     void* _Nullable callbackContext
 );
+
+/**
+ * Free up the memory of the thread that is represented by this handle
+ * @param[in] handle the thread instance handle
+ */
 void tt_thread_free(ThreadHandle handle);
+
+/**
+ * Set the name of a thread
+ * @param[in] handle the thread instance handle
+ * @param[in] name the name to set
+ */
 void tt_thread_set_name(ThreadHandle handle, const char* name);
+
+/**
+ * Set the stack size of the thread (in bytes)
+ * @param[in] handle the thread instance handle
+ * @param[in] the size of the thread in bytes
+ */
 void tt_thread_set_stack_size(ThreadHandle handle, size_t size);
+
+/**
+ * Set the callback for a thread. This method is executed when the thread is started.
+ * @param[in] handle the thread instance handle
+ * @param[in] callback the callback to set
+ * @param[in] callbackContext the data to pass to the callback
+ */
 void tt_thread_set_callback(ThreadHandle handle, ThreadCallback callback, void* _Nullable callbackContext);
+
+/**
+ * Set the priority of a thread
+ * @param[in] handle the thread instance handle
+ * @param[in] priority the priority to set
+ */
 void tt_thread_set_priority(ThreadHandle handle, ThreadPriority priority);
+
+/**
+ * Set the state callback for a thread
+ * @param[in] handle the thread instance handle
+ * @param[in] callback the callback to set
+ * @param[in] callbackContext the data to pass to the callback
+ */
 void tt_thread_set_state_callback(ThreadHandle handle, ThreadStateCallback callback, void* _Nullable callbackContext);
+
+/**
+ * @param[in] handle the thread instance handle
+ * @return the current state of a thread
+ */
 ThreadState tt_thread_get_state(ThreadHandle handle);
+
+/**
+ * Start a thread
+ * @param[in] handle the thread instance handle
+ */
 void tt_thread_start(ThreadHandle handle);
-bool tt_thread_join(ThreadHandle handle);
+
+/**
+ * Wait (block) for the thread to finish.
+ * @param[in] handle the thread instance handle
+ * @warning make sure you manually interrupt any logic in your thread (e.g. by an EventFlag or boolean+Mutex)
+ */
+bool tt_thread_join(ThreadHandle handle, TickType_t timeout);
+
+/**
+ * Get thread id
+ * @param[in] handle the thread instance handle
+ * @return the ThreadId of a thread
+ * */
 ThreadId tt_thread_get_id(ThreadHandle handle);
+
+/**
+ * Get the return code of a thread
+ * @warning crashes when state is not "stopped"
+ * @param[in] handle the thread instance handle
+ * @return the return code of a thread or
+ */
 int32_t tt_thread_get_return_code(ThreadHandle handle);
 
 #ifdef __cplusplus

TactilityC/Source/tt_timer.h

@@ -10,8 +10,10 @@ extern "C" {
 #include <stdint.h>
 #include <stdbool.h>
 
+/** The handle that represents a timer instance */
 typedef void* TimerHandle;
 
+/** The behaviour of the timer */
 typedef enum {
     TimerTypeOnce = 0,    ///< One-shot timer.
     TimerTypePeriodic = 1 ///< Repeating timer.
@@ -20,14 +22,68 @@ typedef enum {
 typedef void (*TimerCallback)(void* context);
 typedef void (*TimerPendingCallback)(void* context, uint32_t arg);
 
+/**
+ * Create a new timer instance
+ * @param[in] callback the callback to call when the timer expires
+ * @param[in] callbackContext the data to pass to the callback
+ */
 TimerHandle tt_timer_alloc(TimerType type, TimerCallback callback, void* callbackContext);
+
+/** Free up the memory of a timer instance */
 void tt_timer_free(TimerHandle handle);
-bool tt_timer_start(TimerHandle handle, TickType_t intervalTicks);
-bool tt_timer_restart(TimerHandle handle, TickType_t intervalTicks);
+
+/**
+ * Start the timer
+ * @param[in] handle the timer instance handle
+ * @parma[in] interval the interval of the timer
+ * @return true when the timer was successfully started
+ */
+bool tt_timer_start(TimerHandle handle, TickType_t interval);
+
+/**
+ * Restart an already started timer
+ * @param[in] handle the timer instance handle
+ * @parma[in] interval the interval of the timer
+ * @return true when the timer was successfully restarted
+ */
+bool tt_timer_restart(TimerHandle handle, TickType_t interval);
+
+/**
+ * Stop a started timer
+ * @param[in] handle the timer instance handle
+ * @return true when the timer was successfully stopped
+ */
 bool tt_timer_stop(TimerHandle handle);
+
+/**
+ * Check if a timer is started
+ * @param[in] handle the timer instance handle
+ * @return true when the timer is started (pending)
+ */
 bool tt_timer_is_running(TimerHandle handle);
+
+/**
+ * Get the expire time of a timer
+ * @param[in] handle the timer instance handle
+ * @return the absolute timestamp at which the timer will expire
+ */
 uint32_t tt_timer_get_expire_time(TimerHandle handle);
-bool tt_timer_set_pending_callback(TimerHandle handle, TimerPendingCallback callback, void* callbackContext, uint32_t callbackArg, TickType_t timeoutTicks);
+
+/**
+ * Set the pending callback for a timer
+ * @param[in] handle the timer instance handle
+ * @param[in] callback the callback to set
+ * @param[in] callbackContext the context to pass to the callback
+ * @param[in] timeout the timeout for setting the callback
+ * @return when the callback was successfully set
+ */
+bool tt_timer_set_pending_callback(TimerHandle handle, TimerPendingCallback callback, void* callbackContext, uint32_t callbackArg, TickType_t timeout);
+
+/**
+ * Set the thread priority for the callback of the timer
+ * @param[in] handle the timer instance handle
+ * @param[in] priority the thread priority to set
+ */
 void tt_timer_set_thread_priority(TimerHandle handle, ThreadPriority priority);
 
 #ifdef __cplusplus