Revision 2:84432add9142, committed 2013-09-03

Comitter:

groletter

Date:

Tue Sep 03 20:24:12 2013 +0000

Parent:

1:2f5a62eb52ad

Commit message:

Added class documentation. Not sure how to do this for pure C code.

Changed in this revision

diff -r 2f5a62eb52ad -r 84432add9142 Communication/Communication.cpp
--- a/Communication/Communication.cpp	Tue Sep 03 08:54:55 2013 +0000
+++ b/Communication/Communication.cpp	Tue Sep 03 20:24:12 2013 +0000
@@ -11,14 +11,17 @@
 
 extern USBSerial serial;
 
+/* ! \fn Gets character from host */
 int mon_get() {
     return serial._getc();
 }
 
+/// Sends character to the host
 int mon_send(char c) {
     return serial._putc(c);
 }
 
+/// Waits for the host to ack
 bool host_wait() {
 	char resp;
 	// FIXME - check buffer size before waiting so 
@@ -31,6 +34,7 @@
     }
 }
 
+/// Listens for connection message from host
 bool check_connection() {
     if (serial.available()) {
         if (mon_get() == 'c') {
@@ -43,7 +47,7 @@
     }
 }
 
-
+/// Sends actual alert to the host
 bool send_alert(alert_type alert) {
     int response;
     mon_send('a'); // Send alert

diff -r 2f5a62eb52ad -r 84432add9142 Communication/Communication.h
--- a/Communication/Communication.h	Tue Sep 03 08:54:55 2013 +0000
+++ b/Communication/Communication.h	Tue Sep 03 20:24:12 2013 +0000
@@ -5,13 +5,53 @@
 #include <stdio.h>
 #include <vector>
 
+/** Function to send an alert to the host
+*
+* @param alert - enum of different allowed alert types
+* @param return - pass or fail based on ack from host
+*/
 bool send_alert(alert_type alert);
+/** Function to wait for an ack from the host.
+*
+* @param return - true if host acked, false otherwise
+*/
 bool host_wait();
+/** Function to check if host is alive
+*
+* Checks to see if there is any data on the serial port.  If so,
+* checks command to see if it is a "connect".
+*
+* @param return - true if host sent connect message, false otherwise
+*/
 bool check_connection();
+/** Function to get character over serial interface 
+*
+* @param return - character received over serial interface
+*/
 char rec_command() ;
+/** Function to send multiple data samples to the host
+*
+* @param samples - vector of strings representing an array of values to be sent to host
+* @param return - true if host properly received data, false otherwise
+*/
 bool send_samples(std::vector<std::string> samples);
+/** Function to receive one sample from the host
+*
+* @param return - one sample value as a double
+*/
 double get_sample(void);
+/** Function to parse messages from the host.  It takes the 
+* motion and temperature class references to be able to set and get values.
+*
+* @param temp - reference to temperature object
+* @param motion - reference to motion object storing motion db, thresholds, etc.
+*/
 void host_command_resp(msg_type msg, Temperature &temp, Motion &motion);
+/** Function to parse the actual character received over serial interface
+* do error checking and if okay passes it on to host_command_resp() method
+*
+* @param msg - Character message received from the host
+*/
 msg_type parse_msg(char msg) ;
 
 #endif

diff -r 2f5a62eb52ad -r 84432add9142 Motion/Motion.h
--- a/Motion/Motion.h	Tue Sep 03 08:54:55 2013 +0000
+++ b/Motion/Motion.h	Tue Sep 03 20:24:12 2013 +0000
@@ -5,12 +5,16 @@
 #include <string>
 #include "HomeMonUtils.h"
 
+/** Simple structure to hold a motion vector - x, y, and z motion
+*/
 struct motion_vec {
     double x;
     double y;
     double z;
 };
 
+/** Motion class stores historical motion alert data and thresholding for alert generation
+*/
 class Motion {
     private: 
       motion_vec min_motion;
@@ -21,12 +25,49 @@
       std::vector<std::string> motion_samples;
 
     public:
+    /**
+    * Instantiate a motion class.  Initialization hard-coded to 
+    * known good values.  Use member functions to modify.
+    */
 	  Motion();
+	  /**
+	  * Allows host to retrieve motion threshold as a vector.
+	  *
+	  * @param return - Returns a motion vector structure with x, y, and z threholds for motion.
+	  */
       motion_vec get_motion_thresh(void);
-	  bool set_motion_thresh(motion_vec);
+      /**
+      * Allows host to set the motion threshold
+      *
+      * @param motion_thresh - Motion vector threshold setting
+      * @param return - pass/faill for set
+      */
+	  bool set_motion_thresh(motion_vec motion_thresh);
+	  /**
+	  * Adds a sample to the motion database.  Units are time in seconds since device booted.
+	  *
+	  * @param motion_sample - represents seconds since device booted that a motion alert occurred.
+	  */
       void add_sample(double motion_sample);
+      /**
+      * Returns all motion samples in the motion database.
+      *
+      * @param return - vector containing strings for all motion alerts (seconds since device booted)
+      */
       const std::vector<std::string> &get_samples();
-	  bool change_max_samples(int);
+      /**
+      * Allows the host to change the motion database size.
+      * WARNING: This may cause sample to be lost due to vector resize operation
+      *
+      * @param num_samples - new size of motion alert DB (max allowed currently 100)
+      * @param return - pass/fail of operation
+      */
+	  bool change_max_samples(int num_samples);
+	  /**
+	  * Returns current database size
+	  *
+	  * @param return - size in samples of motion alert DB
+	  */
 	  int get_max_samples();
 
 };

diff -r 2f5a62eb52ad -r 84432add9142 Temperature/Temperature.h
--- a/Temperature/Temperature.h	Tue Sep 03 08:54:55 2013 +0000
+++ b/Temperature/Temperature.h	Tue Sep 03 20:24:12 2013 +0000
@@ -4,6 +4,9 @@
 #include <vector>
 #include <string>
 
+/** Temperature class stores historical temperature data and tresholds for temperature alerts
+* 
+*/
 class Temperature {
     private: 
 	  double max_temp_limit, min_temp_limit, period_limit, max_samples_limit;
@@ -16,16 +19,78 @@
       std::vector<std::string> temp_samples;
 
     public:
+    /**
+    * Creates a new temperature object.  All parameters
+    * hard coded at first and methods used to set appropriately
+    * based on user's desires.
+    */
 	  Temperature();
+	  /**
+	  * Returns minimum temperature threshold
+	  *
+	  * @param return - mininum temperature threshold
+	  */
       double get_min();
+      /**
+      * Returns maximum temperature threshold
+      *
+      * @param return - maximum temperature threshold
+      */
       double get_max();
+      /**
+      * Returns temperature sampling period in seconds
+      *
+      * @param return - temperature sampling period in seconds
+      */
       double get_period();
-      bool set_min(double);
-      bool set_max(double);
-      bool set_period(double);
+      /**
+      * Sets the minimum temperature threshold for alerts.
+      *
+      * @param min - new minimum temperature threshold for alerts
+      * @param return - indicates success or failure
+      */
+      bool set_min(double min);
+      /**
+      * Sets the maximum temperature threshold for alerts.
+      *
+      * @param max - new maximum temperature threshold for alerts
+      * @param return - indicates success or failure
+      */
+      bool set_max(double max);
+      /**
+      * Sets the temperature period in seconds to store temperature samples in DB
+      *
+      * @param period - termperature sampling period in seconds
+      * @param return - pass or fail of attempt
+      */
+      bool set_period(double period);
+      /**
+      * Method to add a temperature sample to the database
+      *
+      * @param temp_sample - temperature sample to be stored to dB
+      */
       void add_sample(double temp_sample);
-      bool change_max_samples(int);
+      /**
+      * Changes number of samples in temperature database.
+      * Current maximum is 100 samples
+      * WARNING: Changing this may trash samples since vector is resized.
+      *
+      * @param num_samples - Number of samples in DB
+      * @param return - pass fail of attemp 
+      */
+      bool change_max_samples(int num_samples);
+      /**
+      * Returns database size in temperature DB
+      *
+      * @param return - current size of temp DB in samples
+      */
 	  int get_max_samples();
+	  /**
+	  * Returns all temperature samples as strings in the database.
+	  * number returned should match max_samples.
+	  *
+	  * @param return - Reference to vector containing temperature DB as strings
+	  */
       const std::vector<std::string> &get_samples();
 
 };