Added docs for TactilityC

TactilityC/Source/tt_app_alertdialog.h

@@ -8,7 +8,18 @@ extern "C" {
 
 #include <stdint.h>
 
-void tt_app_alertdialog_start(const char* title, const char* message, const char* buttonLabels[], uint32_t buttonLabelCount);
+/**
+ * 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* _Nullable 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.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

@@ -9,19 +9,63 @@ extern "C" {
 
 typedef void* BundleHandle;
 
+/** @return a new Bundle instance */
 BundleHandle tt_bundle_alloc();
+
+/** Dealloc an existing bundle instance */
 void tt_bundle_free(BundleHandle handle);
 
+/**
+ * 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);
+
 /**
- * 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 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.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);
+
+/**
+ * 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, uint16_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, uint16_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