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.

TactilityHeadless/Source/Preferences.h

@@ -5,6 +5,10 @@
 
 namespace tt {
 
+/**
+ * Settings that persist on NVS flash for ESP32.
+ * On simulator, the settings are only in-memory.
+ */
 class Preferences {
 private:
     const char* namespace_;

TactilityHeadless/Source/TactilityHeadless.h

@@ -7,14 +7,20 @@
 
 namespace tt {
 
+/** Initialize the hardware and started the internal services. */
 void initHeadless(const hal::Configuration& config);
 
+/** Provides access to the dispatcher that runs on the main task.
+ * @warning This dispatcher is used for WiFi and might block for some time during WiFi connection.
+ * @return the dispatcher
+ */
 Dispatcher& getMainDispatcher();
 
 } // namespace
 
 namespace tt::hal {
 
+/** Can be called after initHeadless() is called. Will crash otherwise. */
 const Configuration& getConfiguration();
 
 } // namespace

TactilityHeadless/Source/service/ServiceContext.h

@@ -8,6 +8,10 @@ namespace tt::service {
 
 class Paths;
 
+/**
+ * The public representation of a service instance.
+ * @warning Do not store references or pointers to these! You can retrieve them via the Loader service.
+ */
 class ServiceContext {
 
 protected:
@@ -16,9 +20,13 @@ protected:
 
 public:
 
+    /** @return a reference ot the service's manifest */
     virtual const service::ServiceManifest& getManifest() const = 0;
-    virtual std::shared_ptr<void> getData() const = 0;
+    /** @return a shared pointer to the data that is attached to the service */
+    virtual std::shared_ptr<void> _Nullable getData() const = 0;
+    /** Set the data for a service. */
     virtual void setData(std::shared_ptr<void> newData) = 0;
+    /** Retrieve the paths that are relevant to this service */
     virtual std::unique_ptr<Paths> getPaths() const = 0;
 };
 

TactilityHeadless/Source/service/ServiceManifest.h

@@ -9,22 +9,16 @@ class ServiceContext;
 typedef void (*ServiceOnStart)(ServiceContext& service);
 typedef void (*ServiceOnStop)(ServiceContext& service);
 
+/** A ledger that describes the main parts of a service. */
 struct ServiceManifest {
-    /**
-     * 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 {};
 
-    /**
-     * Non-blocking method to call when service is started.
-     */
+    /** Non-blocking method to call when service is started. */
     const ServiceOnStart onStart = nullptr;
 
-    /**
-     * Non-blocking method to call when service is stopped.
-     */
+    /** Non-blocking method to call when service is stopped. */
     const ServiceOnStop onStop = nullptr;
-
 };
 
 } // namespace

TactilityHeadless/Source/service/ServiceRegistry.h

@@ -4,17 +4,40 @@
 
 namespace tt::service {
 
-typedef void (*ManifestCallback)(const ServiceManifest*, void* context);
-
 void initRegistry();
 
+/** Register a service.
+ * @param[in] the service manifest
+ */
 void addService(const ServiceManifest* manifest);
+
+/** Unregister a service.
+ * @param[in] the service manifest
+ */
 void removeService(const ServiceManifest* manifest);
 
+/** Start a service.
+ * @param[in] the service id as defined in its manifest
+ * @return true on success
+ */
 bool startService(const std::string& id);
+
+/** Stop a service.
+ * @param[in] the service id as defined in its manifest
+ * @return true on success or false when service wasn't running.
+ */
 bool stopService(const std::string& id);
 
+/** Find a service manifest by its id.
+ * @param[in] id the id as defined in the manifest
+ * @return the matching manifest or nullptr when it wasn't found
+ */
 const ServiceManifest* _Nullable findManifestId(const std::string& id);
+
+/** Find a service by its manifest id.
+ * @param[in] id the id as defined in the manifest
+ * @return the service context or nullptr when it wasn't found
+ */
 ServiceContext* _Nullable findServiceById(const std::string& id);
 
 } // namespace

TactilityHeadless/Source/service/wifi/Wifi.h

@@ -84,53 +84,42 @@ WifiRadioState getRadioState();
  */
 void scan();
 
-/**
- * @return true if wifi is actively scanning
- */
+/** @return true if wifi is actively scanning */
 bool isScanning();
 
-/**
- * @return true the ssid name or empty string
- */
+/** @return true the ssid name or empty string */
 std::string getConnectionTarget();
 
-/**
- * @brief Returns the access points from the last scan (if any). It only contains public APs.
- */
+/** @return the access points from the last scan (if any). It only contains public APs. */
 std::vector<WifiApRecord> getScanResults();
 
 /**
  * @brief Overrides the default scan result size of 16.
- * @param records the record limit for the scan result (84 bytes per record!)
+ * @param[in] records the record limit for the scan result (84 bytes per record!)
  */
 void setScanRecords(uint16_t records);
 
 /**
  * @brief Enable/disable the radio. Ignores input if desired state matches current state.
- * @param enabled
+ * @param[in] enabled
  */
 void setEnabled(bool enabled);
 
 /**
  * @brief Connect to a network. Disconnects any existing connection.
  * Returns immediately but runs in the background. Results are through pubsub.
- * @param ap
+ * @param[in] ap
+ * @param[in] remember whether to save the ap data to the settings upon successful connection
  */
 void connect(const settings::WifiApSettings* ap, bool remember);
 
-/**
- * @brief Disconnect from the access point. Doesn't have any effect when not connected.
- */
+/** @brief Disconnect from the access point. Doesn't have any effect when not connected. */
 void disconnect();
 
-/**
- * Return true if the connection isn't unencrypted.
- */
+/** @return true if the connection isn't unencrypted. */
 bool isConnectionSecure();
 
-/**
- * Returns the RSSI value (negative number) or return 1 when not connected
- */
+/** @return the RSSI value (negative number) or return 1 when not connected. */
 int getRssi();
 
 } // namespace

TactilityHeadless/Source/service/wifi/WifiEsp.cpp

@@ -780,7 +780,7 @@ static void dispatchConnect(std::shared_ptr<void> context) {
     TT_LOG_I(TAG, "Waiting for EventFlag by event_handler()");
 
     if (bits & WIFI_CONNECTED_BIT) {
-        wifi->setSecureConnection(wifi_config.sta.password[0] != 0x00);
+        wifi->setSecureConnection(wifi_config.sta.password[0] != 0x00U);
         wifi->setRadioState(WIFI_RADIO_CONNECTION_ACTIVE);
         publish_event_simple(wifi, WifiEventTypeConnectionSuccess);
         TT_LOG_I(TAG, "Connected to %s", wifi->connection_target.ssid);