comments

include/puara/descriptors/touchFeatures.h

@@ -1,4 +1,3 @@
-
 #include <puara/utils.h>
 #include <puara/utils/leakyintegrator.h>
 
@@ -7,20 +6,36 @@
 namespace puara_gestures
 {
 
+/**
+ * @brief Base class representing a generic touch feature.
+ * This class provides a framework for interpreting touch features based on
+ * movement input. It uses a leaky integrator for smoothing and allows derived
+ * classes to define specific integration behavior.
+ */
 class TouchFeature
 {
 public:
-  /** ffff, 0--? (~cm/s)  */
+  /**
+   * @brief The computed feature value (e.g., intensity or rate).
+   * Initialized to 0. Measured in ~cm/s.
+   */
   float value{};
 
+  /**
+   * @brief Resets the feature value to its default state.
+   */
   void reset() { value = 0; }
 
+  /**
+   * @brief Updates the feature based on the movement from the last update.
+   * @param movement The measured movement value to process.
+   */
   void update(float movement)
   {
-    // no movement since the last update -> potentially reset the value
+    // No movement since the last update -> potentially reset the value
     if(movement == 0)
     {
-      // only reset the value once we've gotten 0 movements for 10 times
+      // Only reset the value once we've gotten 0 movements for 10 times
       if(++counter < 10)
         return;
 
@@ -29,12 +44,12 @@ class TouchFeature
       else
         integrate(movement);
     }
-    //large movement -> so integrate 0?
+    // Large movement -> integrate with 0
     else if(std::abs(movement) > 1)
     {
       integrate(0);
     }
-    //goldilocks movement -> integrate and reset the counter
+    // Goldilocks movement -> integrate and reset the counter
     else
     {
       integrate(movement);
@@ -43,26 +58,58 @@ class TouchFeature
   }
 
 protected:
+  /**
+   * @brief A leaky integrator for smoothing the feature values.
+   */
   utils::LeakyIntegrator integrator{0.0f, 0.0f, 0.7f, 100, 0};
 
 private:
+  /**
+   * @brief Abstract method to integrate input into the feature value.
+   * @param input The input value to be integrated.
+   */
   virtual void integrate(float input) = 0;
+
+  /**
+   * @brief A counter for tracking consecutive zero-movement updates.
+   */
   int counter{};
 };
 
+/**
+ * @brief Derived class implementing the "brush" touch feature.
+ * The feature value is a signed value that increases or
+ * decreases based on the brush movement direction.
+ */
 class Brush : public TouchFeature
 {
+  /**
+   * @brief Integrates movement input into the brush feature value.
+   * Applies a scaling factor to the input and uses the leaky integrator.
+   * @param movement The input movement to integrate.
+   */
   void integrate(float movement) override
   {
     value = integrator.integrate(movement * .15);
   }
 };
 
+/**
+ * @brief Derived class implementing the "rub" touch feature.
+ * The feature value is based on the absolute value of movement,
+ * this increasing as the sensors are rubbed in any direction.
+ */
 class Rub : public TouchFeature
 {
+  /**
+   * @brief Integrates movement input into the rub feature value.
+   * Takes the absolute value of the input before applying the leaky integrator.
+   * @param movement The input movement to integrate.
+   */
   void integrate(float movement) override
   {
     value = integrator.integrate(std::abs(movement * .15));
   }
 };
+
 }