Diff: Distance_HC_SR04.cpp

Revision:

5:2f6992aad3a0

Parent:

4:71f01fbc9246

Child:

6:5beda7c318d5

--- a/Distance_HC_SR04.cpp	Tue Dec 22 09:29:04 2015 +0000
+++ b/Distance_HC_SR04.cpp	Tue Dec 22 11:22:56 2015 +0000
@@ -11,8 +11,12 @@
         _state = IDLE;
     }
 
-    /** Start the measurement. Starts the measurement (pulse on "trig" output) and checks proper value of "echo" signal.
-     *  Sets FSM to STARTED in case that "echo" reacts correctly. Otherwise ERROR_SIG state is being set.
+    /** Start the measurement in asynchronous non-blocking mode.
+     * 
+     *  Generates pulse on "trig" output and checks proper value of "echo" signal. Sets FSM STATE and exits.
+     *
+     *  If "echo" is low right after "trig" pulse is generated, sets FSM state to "STARTED".
+     *  In other case FSM sate is set to "ERROR_SIG".
      *
      */
     void Distance_HC_SR04::trigger(void) {
@@ -40,7 +44,7 @@
         return;
     }
 
-    /** Returns a state measurement FSM is currently in.
+    /** Returns a state of measurement FSM in asynchronous non-blocking mode.
      *
      *  This function is used in asynchronous non-blocking mode.
      *
@@ -51,7 +55,9 @@
         return _state;
     }
 
-    /** Resets whole device and prepares for triggering next measurement. FSM set to IDLE state.
+    /** Reset whole device and prepare for triggering of the next measurement in asynchronous non-blocking mode. 
+     *
+     *  FSM set to IDLE state.
      *
      */
     void Distance_HC_SR04::reset(void) {
@@ -63,7 +69,7 @@
         _timer.reset();
     }
 
-    /** Returnes duration of "echo" pulse (microseconds) in case thate state is "COMPLETED".
+    /** Return measured duration of "echo" pulse in "COMPLETED" state. Use in asynchronous non-blocking mode.
      *
      *  New measurement is not started. Uses result from last measurement.
      *
@@ -74,7 +80,8 @@
         return _ticks_us;
     }
 
-    /** Returns a distance of the obstacle in milimeters calculated from duration of "echo" pulse.
+    /** Return distance of the obstacle. Use in asynchronous non-blocking mode.
+     *
      *  New measurement is not started. Uses result from last measurement.
      *
      * @returns
@@ -97,29 +104,31 @@
       *
       * @param coeff Coeficient for multiplication with pulse duration in microseconds
       * @returns
-      *   void
+      *   void -
       */    
     void Distance_HC_SR04::setCoeff(float coeff) {
         _coeff = coeff;
     }
 
-    /** Measure and return the distance.
+    /** Measure and return the distance in synchronous blocking mode.
+      *
+      * New measurement is started and the code waits for measurement completion or timeout.
       *
       * @param void -
       * @returns
-      *   float value of distance > 0.0f in case of a success,
-      *   0.0f in case of an error
+      *   float value of distance > 0.0f in case of a success, 0.0f in case of an error
       */    
     float Distance_HC_SR04::measureDistance(void) {
         return measureTicks()*_coeff;
     }
 
-    /** Measure and return "echo" pulse duration.
+    /** Measure and return "echo" pulse duration in synchronous blocking mode.
+      *
+      * New measurement is started and the code waits for measurement completion or timeout.
       *
       * @param void -
       * @returns
-      *   uint32_t value of distance > 0 in case of a success,
-      *   0 in case of an error
+      *   uint32_t value of distance > 0 in case of a success, 0 in case of an error
       */    
     uint32_t Distance_HC_SR04::measureTicks(void) {
         reset();
@@ -143,7 +152,7 @@
         return _ticks_us;
     }
 
-    /** Timeout callback function.
+    /** Timeout callback function (private).
       *
       * @param void -
       * @returns
@@ -154,7 +163,7 @@
             _state = TIMEOUT;
     }
 
-    /** Rising edge callback function.
+    /** Rising edge callback function (private).
       *
       * @param void -
       * @returns
@@ -166,7 +175,7 @@
         }
     }
 
-    /** Falling edge callback function.
+    /** Falling edge callback function (private).
       *
       * @param void -
       * @returns