Update docs and fix bugs (#149)

Improved the docs for the 3 main Tactility projects. I also fixed some inaccuracies and bugs in certain APIs as I went through the code.

Tactility/Source/app/AppContext.h

@@ -16,8 +16,8 @@ typedef union {
 } Flags;
 
 /**
- * A limited representation of the application instance.
- * Do not store references or pointers to these!
+ * The public representation of an application instance.
+ * @warning Do not store references or pointers to these! You can retrieve them via the service registry.
  */
 class AppContext {
 

Tactility/Source/app/AppManifest.h

@@ -11,7 +11,8 @@ namespace tt::app {
 
 class AppContext;
 
-typedef enum {
+/** Application types */
+enum Type {
     /** Boot screen, shown before desktop is launched. */
     TypeBoot,
     /** A desktop app sits at the root of the app stack managed by the Loader service */
@@ -24,8 +25,9 @@ typedef enum {
     TypeSettings,
     /** User-provided apps. */
     TypeUser
-} Type;
+};
 
+/** Result status code for application result callback. */
 typedef enum {
     ResultOk,
     ResultCancelled,
@@ -39,49 +41,31 @@ typedef void (*AppOnHide)(AppContext& app);
 typedef void (*AppOnResult)(AppContext& app, Result result, const Bundle& resultData);
 
 struct AppManifest {
-    /**
-     * The identifier by which the app is launched by the system and other apps.
-     */
+    /** The identifier by which the app is launched by the system and other apps. */
     std::string id;
 
-    /**
-     * The user-readable name of the app. Used in UI.
-     */
+    /** The user-readable name of the app. Used in UI. */
     std::string name;
 
-    /**
-     * Optional icon.
-     */
+    /** Optional icon. */
     std::string icon = {};
 
-    /**
-     * App type affects launch behaviour.
-     */
+    /** App type affects launch behaviour. */
     Type type = TypeUser;
 
-    /**
-     * Non-blocking method to call when app is started.
-     */
+    /** Non-blocking method to call when app is started. */
     AppOnStart onStart = nullptr;
 
-    /**
-     * Non-blocking method to call when app is stopped.
-     */
+    /** Non-blocking method to call when app is stopped. */
     AppOnStop _Nullable onStop = nullptr;
 
-    /**
-     * Non-blocking method to create the GUI
-     */
+    /** Non-blocking method to create the GUI. */
     AppOnShow _Nullable onShow = nullptr;
 
-    /**
-     * Non-blocking method, called before gui is destroyed
-     */
+    /** Non-blocking method, called before gui is destroyed. */
     AppOnHide _Nullable onHide = nullptr;
 
-    /**
-     * Handle the result for apps that are launched
-     */
+    /** Handle the result for apps that are launched. */
     AppOnResult _Nullable onResult = nullptr;
 };
 

Tactility/Source/app/ElfApp.cpp

@@ -22,7 +22,7 @@ bool startElfApp(const std::string& filePath) {
     assert(elfFileData == nullptr);
 
     size_t size = 0;
-    elfFileData = file::readBinary(filePath.c_str(), size);
+    elfFileData = file::readBinary(filePath, size);
     if (elfFileData == nullptr) {
         return false;
     }

Tactility/Source/app/ManifestRegistry.h

@@ -6,8 +6,16 @@
 
 namespace tt::app {
 
+/** Register an application with its manifest */
 void addApp(const AppManifest* manifest);
+
+/** Find an application manifest by its id
+ * @param[in] id the manifest id
+ * @return the application manifest if it was found
+ */
 const AppManifest _Nullable* findAppById(const std::string& id);
+
+/** @return a list of all registered apps. This includes user and system apps. */
 std::vector<const AppManifest*> getApps();
 
 } // namespace

Tactility/Source/app/crashdiagnostics/QrUrl.cpp

@@ -9,10 +9,10 @@
 #include <esp_cpu_utils.h>
 
 std::string getUrlFromCrashData() {
-    auto* crash_data = getRtcCrashData();
-    auto* stack_buffer = (uint32_t*) malloc(crash_data->callstackLength * 2 * sizeof(uint32_t));
-    for (int i = 0; i < crash_data->callstackLength; ++i) {
-        const CallstackFrame&frame = crash_data->callstack[i];
+    auto crash_data = getRtcCrashData();
+    auto* stack_buffer = (uint32_t*) malloc(crash_data.callstackLength * 2 * sizeof(uint32_t));
+    for (int i = 0; i < crash_data.callstackLength; ++i) {
+        const CallstackFrame&frame = crash_data.callstack[i];
         uint32_t pc = esp_cpu_process_stack_pc(frame.pc);
 #if CRASH_DATA_INCLUDES_SP
         uint32_t sp = frame.sp;
@@ -30,7 +30,7 @@ std::string getUrlFromCrashData() {
     stream << "&a=" << CONFIG_IDF_TARGET; // Architecture
     stream << "&s="; // Stacktrace
 
-    for (int i = crash_data->callstackLength - 1; i >= 0; --i) {
+    for (int i = crash_data.callstackLength - 1; i >= 0; --i) {
         uint32_t pc = stack_buffer[(i * 2)];
         stream << std::hex << pc;
 #if CRASH_DATA_INCLUDES_SP