Revision 2:0a64af7ab7c6, committed 2013-08-22

Comitter:

ccoleman

Date:

Thu Aug 22 21:48:25 2013 +0000

Parent:

1:8408853a700c

Child:

3:1afe0cfab2d1

Commit message:

Updated documentation of CarAPI.

Changed in this revision

--- a/CarAPI.h	Thu Aug 22 21:11:14 2013 +0000
+++ b/CarAPI.h	Thu Aug 22 21:48:25 2013 +0000
@@ -22,67 +22,100 @@
 
 /******************************** Wheels and Motor ********************************/
 
-/** turn the car.  turnAngle should be between [-1,1] */
+/** Turn the car.  
+  * @param turnAngle value between [-1,1]. Negative indicates turning left, and
+  *        positive indicates turning right.
+  */
 void turn(float turnAngle);
 
-/** move forward with the given power, turn angle, for a specified time */
+/** Move forward with the given power for a specified time.
+  * @param power Value between [-1, 1]. Negative indicates reverse, positive indicates forward motion.
+  * @param seconds Amount of time in seconds which the wheels will rotate at the given power.
+  */
 void move(float power, float seconds);
 
-/** move forward with the given powers for each wheel, turn angle, for a specified time */
+/** Move forward with the given powers for each wheel for a specified time.
+  * @param leftWheelPower Value between [-1, 1]. Negative values indicate left wheel will rotate backward,
+  *        positive values indicate left wheel will rotate forward. More positive and more negative indicate 
+  *        more power in the indicated directions.
+  * @param rightWheelPower Value between [-1, 1]. Negative values indicate right wheel will rotate backward,
+  *        positive values indicate right wheel will rotate forward. More positive and more negative indicate 
+  *        more power in the indicated directions.
+  * @param seconds Amount of time in seconds the wheels will rotate at the given powers.
+  */
 void move(float leftWheelPower, float rightWheelPower,  float seconds);
 
-/** lock the wheels */
+/** Lock the wheels. */
 void parkingBrake();
 
 /******************************** INPUTS AND OUTPUTS ********************************/
-/** check to see if the car is crashing into something */
+
+/** Check to see if the car is crashing into something.
+  * @return True if car is coming to an abrupt halt, else false.
+  */
 bool checkIsCrashing();
 
-/** Return the line direction
- *  line to the left of center. return [-1,0
- *  line to the right of center. return (0,1]
- *  line in center. return 0
+/** Get the line direction with respect to the car.
+ *  @return Floating point number. [-1,0) if line is to the left of center,
+ *          (0,1] if the line is to the right of center,
+ *          or zero (0) if line is in the center.
  */
 float lineDirection();
 
-/* toggle led 0 */
+/* Toggle LED 0. */
 void toggleLED0();
 
-/* toggle led 1 */
+/* Toggle LED 1. */
 void toggleLED1();
 
-/* toggle led 2 */
+/* Toggle LED 2. */
 void toggleLED2();
 
-/* toggle led 3 */
+/* Toggle LED 3. */
 void toggleLED3();
 
-/** is Button B pressed */
+/** Check if Button B was pressed. */
 bool isButtonBPressed();
 
-/** read Potentiometer 0. returns [-1,1] */
+/** Read Potentiometer 0.
+  * @return Value between [-1,1]. */
 float getPot0();
 
-/** read Potentiometer 1. returns  [-1,1] */
+/** Read Potentiometer 1.
+  * @return Value between [-1,1]. */
 float getPot1();
 
-/** How much battery remains. returns  [0,1] */
+/** Get remaining battery charge.
+  * @return Value between [0,1]. */
 float batteryLife();
 
 /******************************** Changing Variables ********************************/
-/** set the base turn offset*/
+/** Set the base turn offset to compensate for imperfect hardware configuration.
+  * @param _turnOffset New value for servo turn offset. Accepted values between [-0.7, 0.7].
+  */
 void setOffset(float _turnOffset);
 
-/** get the base turn offset */
+/** Get the current value of the servo turn offset.
+  * @return Value of the current servo turn offset, between [-0.7, 0.7].
+  */
 float getOffset();
 
-/** set the base crash sensitivity*/
+/** Set the base crash sensitivity. 
+  * @param _sensitivity Value to be set as the new crash sensitivity. Accepted values between 
+  *        [0, 1]. A higher value indicates lower sensitivity, and a lower value indicates higher 
+  *        sensitivity.
+  */
 void setCrashSensitivity(float _sensitivity);
 
-/** return the crash sensitivity */
+/** Return the crash sensitivity.
+  * @return Value of the current crash sensitivity, between [-1, 1]. A higher value indicates 
+  *         lower sensitivity, and a lower value indicates higher sensitivity.
+  */
 float getCrashSensitivity();
 
-/** turn on debugging.  prints each method call to the serial port*/
+/** Turn on debugging. Prints each method call to the serial port.
+  * @param _debug True to turn on debugging, false to turn it off.
+  */
 void setDebug(bool _debug);