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/service/gui/Gui.h

@@ -9,12 +9,11 @@ typedef struct Gui Gui;
 
 /**
  * Set the app viewport in the gui state and request the gui to draw it.
- *
- * @param app
- * @param on_show
- * @param on_hide
+ * @param[in] app
+ * @param[in] onShow
+ * @param[in] onHide
  */
-void showApp(app::AppContext& app, ViewPortShowCallback on_show, ViewPortHideCallback on_hide);
+void showApp(app::AppContext& app, ViewPortShowCallback onShow, ViewPortHideCallback onHide);
 
 /**
  * Hide the current app's viewport.
@@ -25,7 +24,7 @@ void hideApp();
 
 /**
  * Show the on-screen keyboard.
- * @param textarea the textarea to focus the input for
+ * @param[in] textarea the textarea to focus the input for
  */
 void keyboardShow(lv_obj_t* textarea);
 
@@ -47,7 +46,7 @@ bool keyboardIsEnabled();
  * Glue code for the on-screen keyboard and the hardware keyboard:
  *  - Attach automatic hide/show parameters for the on-screen keyboard.
  *  - Registers the textarea to the default lv_group_t for hardware keyboards.
- * @param textarea
+ * @param[in] textarea
  */
 void keyboardAddTextArea(lv_obj_t* textarea);
 

Tactility/Source/service/gui/ViewPort.h

@@ -26,26 +26,22 @@ typedef struct ViewPort {
 } ViewPort;
 
 /** ViewPort allocator
- *
  * always returns view_port or stops system if not enough memory.
  * @param app
- * @param on_show Called to create LVGL widgets
- * @param on_hide Called before clearing the LVGL widget parent
- *
- * @return     ViewPort instance
+ * @param onShow Called to create LVGL widgets
+ * @param onHide Called before clearing the LVGL widget parent
+ * @return ViewPort instance
  */
 ViewPort* view_port_alloc(
     app::AppContext& app,
-    ViewPortShowCallback on_show,
-    ViewPortHideCallback on_hide
+    ViewPortShowCallback onShow,
+    ViewPortHideCallback onHide
 );
 
-/** ViewPort deallocator
- *
+/** ViewPort destruction
  * Ensure that view_port was unregistered in GUI system before use.
- *
- * @param      view_port  ViewPort instance
+ * @param viewPort ViewPort instance
  */
-void view_port_free(ViewPort* view_port);
+void view_port_free(ViewPort* viewPort);
 
 } // namespace

Tactility/Source/service/loader/Loader.h

@@ -26,11 +26,10 @@ typedef enum {
  */
 void startApp(const std::string& id, bool blocking = false, std::shared_ptr<const Bundle> _Nullable parameters = nullptr);
 
-/**
- * @brief Stop the currently showing app. Show the previous app if any app was still running.
- */
+/** @brief Stop the currently showing app. Show the previous app if any app was still running. */
 void stopApp();
 
+/** @return the currently running app (it is only ever null before the splash screen is shown) */
 app::AppContext* _Nullable getCurrentApp();
 
 /**

Tactility/Source/service/screenshot/Screenshot.cpp

@@ -39,7 +39,7 @@ void ScreenshotService::startApps(const char* path) {
     }
 }
 
-void ScreenshotService::startTimed(const char* path, uint8_t delay_in_seconds, uint8_t amount) {
+void ScreenshotService::startTimed(const char* path, uint8_t delayInSeconds, uint8_t amount) {
     auto scoped_lockable = mutex.scoped();
     if (!scoped_lockable->lock(50 / portTICK_PERIOD_MS)) {
         TT_LOG_W(TAG, LOG_MESSAGE_MUTEX_LOCK_FAILED);
@@ -49,7 +49,7 @@ void ScreenshotService::startTimed(const char* path, uint8_t delay_in_seconds, u
     if (task == nullptr || task->isFinished()) {
         task = std::make_unique<ScreenshotTask>();
         mode = ScreenshotModeTimed;
-        task->startTimed(path, delay_in_seconds, amount);
+        task->startTimed(path, delayInSeconds, amount);
     } else {
         TT_LOG_W(TAG, "Screenshot task already running");
     }

Tactility/Source/service/screenshot/Screenshot.h

@@ -16,8 +16,10 @@ typedef enum {
     ScreenshotModeApps
 } Mode;
 
-
 class ScreenshotService {
+
+private:
+
     Mutex mutex;
     std::unique_ptr<ScreenshotTask> task;
     Mode mode = ScreenshotModeNone;
@@ -25,9 +27,23 @@ class ScreenshotService {
 public:
 
     bool isTaskStarted();
+
+    /** The state of the service. */
     Mode getMode();
+
+    /** @brief Start taking screenshot whenever an app is started
+     * @param[in] path the path to store the screenshots at
+     */
     void startApps(const char* path);
-    void startTimed(const char* path, uint8_t delay_in_seconds, uint8_t amount);
+
+    /** @brief Start taking screenshots after a certain delay
+     * @param[in] path the path to store the screenshots at
+     * @param[in] delayInSeconds the delay before starting (and between successive screenshots)
+     * @param[in] amount 0 = indefinite, >0 for a specific
+     */
+    void startTimed(const char* path, uint8_t delayInSeconds, uint8_t amount);
+
+    /** @brief Stop taking screenshots */
     void stop();
 };
 

Tactility/Source/service/screenshot/ScreenshotTask.h

@@ -35,22 +35,18 @@ public:
     ~ScreenshotTask();
 
     /** @brief Start taking screenshots after a certain delay
-     * @param task the screenshot task
-     * @param path the path to store the screenshots at
-     * @param delay_in_seconds the delay before starting (and between successive screenshots)
-     * @param amount 0 = indefinite, >0 for a specific
+     * @param[in] path the path to store the screenshots at
+     * @param[in] delayInSeconds the delay before starting (and between successive screenshots)
+     * @param[in] amount 0 = indefinite, >0 for a specific
      */
-    void startTimed(const char* path, uint8_t delay_in_seconds, uint8_t amount);
+    void startTimed(const char* path, uint8_t delayInSeconds, uint8_t amount);
 
     /** @brief Start taking screenshot whenever an app is started
-     * @param task the screenshot task
-     * @param path the path to store the screenshots at
+     * @param[in] path the path to store the screenshots at
      */
     void startApps(const char* path);
 
-    /** @brief Stop taking screenshots
-     * @param task the screenshot task
-     */
+    /** @brief Stop taking screenshots */
     void stop();
 
     void taskMain();