Index: SystemComm.c
===================================================================
diff -u -r6520e649188757399c2dfd58a30af80d96256295 -r5fb988facecb08dceb2bba1c462d3097b53617f0
--- SystemComm.c	(.../SystemComm.c)	(revision 6520e649188757399c2dfd58a30af80d96256295)
+++ SystemComm.c	(.../SystemComm.c)	(revision 5fb988facecb08dceb2bba1c462d3097b53617f0)
@@ -45,18 +45,18 @@
 
 // ********** private definitions **********
 
-#define CAN_XMIT_PACKET_TIMEOUT_MS      200     ///< If transmitted CAN frame does not cause a transmit complete interrupt within this time, re-send or move on
-#define MAX_XMIT_RETRIES                5       ///< Maximum number of retries on no transmit complete interrupt timeout
+#define CAN_XMIT_PACKET_TIMEOUT_MS      200         ///< If transmitted CAN frame does not cause a transmit complete interrupt within this time, re-send or move on
+#define MAX_XMIT_RETRIES                5           ///< Maximum number of retries on no transmit complete interrupt timeout
 
-#define MSG_NOT_ACKED_TIMEOUT_MS        250     ///< Maximum time for a Denali message that requires ACK to be ACK'd
+#define MSG_NOT_ACKED_TIMEOUT_MS        250         ///< Maximum time for a Denali message that requires ACK to be ACK'd
 
-#define MSG_NOT_ACKED_MAX_RETRIES       10      ///< Maximum number of times a message that requires ACK that was not ACK'd can be re-sent before alarm
-#define PENDING_ACK_LIST_SIZE           25      ///< Maximum number of Denali messages that can be pending ACK at any given time
+#define MSG_NOT_ACKED_MAX_RETRIES       10          ///< Maximum number of times a message that requires ACK that was not ACK'd can be re-sent before alarm
+#define PENDING_ACK_LIST_SIZE           25          ///< Maximum number of Denali messages that can be pending ACK at any given time
 
-#define PENDING_ACK_LIST_OVERRIDE_UI_CHANNEL    1                                     ///< Value for determining UI channel when Pending ACKs are overriden.
-#define PENDING_ACK_LIST_OVERRIDE_DG_CHANNEL    2                                     ///< Value for determining DG channel when Pending ACKs are overriden.
-#define PENDING_ACK_LIST_OVERRIDE_TD_CHANNEL    3                                     ///< Value for determining TD channel when Pending ACKs are overriden.
-#define PENDING_ACK_LIST_OVERRIDE_RO_CHANNEL    4                                     ///< Value for determining RO channel when Pending ACKs are overriden.
+#define PENDING_ACK_LIST_OVERRIDE_UI_CHANNEL    1   ///< Value for determining UI channel when Pending ACKs are overriden.
+#define PENDING_ACK_LIST_OVERRIDE_DG_CHANNEL    2   ///< Value for determining DG channel when Pending ACKs are overriden.
+#define PENDING_ACK_LIST_OVERRIDE_TD_CHANNEL    3   ///< Value for determining TD channel when Pending ACKs are overriden.
+#define PENDING_ACK_LIST_OVERRIDE_RO_CHANNEL    4   ///< Value for determining RO channel when Pending ACKs are overriden.
 
 #pragma pack(push, 1)
 
@@ -76,13 +76,13 @@
 
 // ********** private data **********
 
-static U08 lastCANPacketSent[ CAN_FRAME_PAYLOAD_SIZE ];                     ///< Keep last packet sent on CAN bus in case we need to re-send.
-static CAN_MESSAGE_BOX_T lastCANPacketSentChannel = (CAN_MESSAGE_BOX_T)0;   ///< Keep channel last packet was sent on CAN bus in case we need to re-send.
-static U32 lastCANPacketSentTimeStamp = 0;                                  ///< Keep time last packet sent on CAN bus so we can timeout on transmission attempt.
-static U32 canXmitRetryCtr = 0;                                             ///< Counter for CAN transmit retries.
+static U08 lastCANPacketSent[ CAN_FRAME_PAYLOAD_SIZE ];                         ///< Keep last packet sent on CAN bus in case we need to re-send.
+static CAN_MESSAGE_BOX_T lastCANPacketSentChannel;                              ///< Keep channel last packet was sent on CAN bus in case we need to re-send.
+static U32 lastCANPacketSentTimeStamp;                                          ///< Keep time last packet sent on CAN bus so we can timeout on transmission attempt.
+static U32 canXmitRetryCtr;                                                     ///< Counter for CAN transmit retries.
 
-static volatile PENDING_ACK_RECORD_T pendingAckList[ PENDING_ACK_LIST_SIZE ];    ///< List of outgoing messages that are awaiting an ACK
-static OVERRIDE_U32_T pendingACKOverride = { 0, 0, 0, 0 };                  ///< Pending ACK override data structure.
+static volatile PENDING_ACK_RECORD_T pendingAckList[ PENDING_ACK_LIST_SIZE ];   ///< List of outgoing messages that are awaiting an ACK
+static OVERRIDE_U32_T pendingACKOverride = { 0, 0, 0, 0 };                      ///< Pending ACK override data structure.
 
 // ********** private function prototypes **********
 
@@ -99,14 +99,18 @@
 
 /*********************************************************************//**
  * @brief
- * The initSystemComm function initializes the SystemComm module.
- * @details Inputs: none
- * @details Outputs: SystemComm module initialized.
+ * The initSystemComm function initializes the SystemComm unit.
+ * @details \b Inputs: none
+ * @details \b Outputs: SystemComm unit variables initialized.
  * @return none
  *************************************************************************/
 void initSystemComm( void )
 {
-    U32 i;
+    U32 i;
+
+    lastCANPacketSentTimeStamp = 0;
+    canXmitRetryCtr = 0;
+    lastCANPacketSentChannel = (CAN_MESSAGE_BOX_T)0;
 
     // Initialize pending ACK list
     for ( i = 0; i < PENDING_ACK_LIST_SIZE; i++ )
@@ -117,9 +121,11 @@
 
 /*********************************************************************//**
  * @brief
- * The execSystemCommRx function manages received data from other sub-systems.
- * @details Inputs: none
- * @details Outputs: Incoming messages parsed and processed.
+ * The execSystemCommRx function manages received data from other sub-systems.
+ * @note This function should be called periodically to keep up with incoming
+ * data on CAN bus.
+ * @details \b Inputs: none
+ * @details \b Outputs: Incoming messages parsed and processed.
  * @return none
  *************************************************************************/
 void execSystemCommRx( void )
@@ -147,8 +153,11 @@
  * @brief
  * The execSystemCommTx function manages data to be transmitted to other
  * sub-systems.
- * @details Inputs: none
- * @details Outputs: Outgoing messages transmitted.
+ * @note This function should be called periodically to keep up with outgoing
+ * data being queued for transmit on CAN bus.
+ * @details \b Inputs: lastCANPacketSentTimeStamp, canXmitRetryCtr, lastCANPacketSentChannel
+ * @details \b Outputs: Outgoing message transmission from outgoing CAN buffers
+ * is initiated
  * @return none
  *************************************************************************/
 void execSystemCommTx( void )
@@ -190,13 +199,15 @@
 
 /*********************************************************************//**
  * @brief
- * The handleCANMsgInterrupt function handles a CAN message interrupt.
- * This may have occurred because a CAN packet transmission has completed
- * or because a CAN packet has been received.  The appropriate handler is
- * called.
- * @details Inputs: none
- * @details Outputs: message interrupt handled
- * @param srcCANBox which CAN message box triggered this interrupt
+ * The handleCANMsgInterrupt function handles a CAN frame interrupt from
+ * a given CAN mail box.
+ * This may have occurred because a CAN frame transmission has completed
+ * or because a CAN frame has been received.  The appropriate handler is
+ * called.
+ * @details \b Alarm: ALARM_ID_TD_SOFTWARE_FAULT if invalid CAN mail box given.
+ * @details \b Inputs: none
+ * @details \b Outputs: message interrupt handled
+ * @param srcCANBox which CAN mail box triggered this interrupt
  * @return none
  *************************************************************************/
 void handleCANMsgInterrupt( CAN_MESSAGE_BOX_T srcCANBox )
@@ -240,12 +251,12 @@
 
 /*********************************************************************//**
  * @brief
- * The isCANBoxForXmit function determines whether a given CAN message box
+ * The isCANBoxForXmit function determines whether a given CAN mail box
  * is configured for transmit.
- * @details Inputs: CAN_OUT_BUFFERS[]
- * @details Outputs: none
- * @param srcCANBox which CAN message box to check
- * @return TRUE if the given CAN message box is configured for transmit, FALSE if not.
+ * @details \b Inputs: CAN_OUT_BUFFERS[]
+ * @details \b Outputs: none
+ * @param srcCANBox which CAN mail box to determine configuration for
+ * @return TRUE if the given CAN mail box is configured for transmit, FALSE if not.
  *************************************************************************/
 BOOL isCANBoxForXmit( CAN_MESSAGE_BOX_T srcCANBox )
 {
@@ -266,12 +277,12 @@
 
 /*********************************************************************//**
  * @brief
- * The isCANBoxForRecv function determines whether a given CAN message box
+ * The isCANBoxForRecv function determines whether a given CAN mail box
  * is configured for receiving.
- * @details Inputs: CAN_IN_BUFFERS[]
- * @details Outputs: none
- * @param srcCANBox which CAN message box to check
- * @return TRUE if the given CAN message box is configured for receiving, FALSE if not.
+ * @details \b Inputs: CAN_IN_BUFFERS[]
+ * @details \b Outputs: none
+ * @param srcCANBox which CAN mail box to determine configuration for
+ * @return TRUE if the given CAN mail box is configured for receiving, FALSE if not.
  *************************************************************************/
 BOOL isCANBoxForRecv( CAN_MESSAGE_BOX_T srcCANBox )
 {
@@ -298,12 +309,12 @@
 
 /*********************************************************************//**
  * @brief
- * The findNextHighestPriorityCANPacketToTransmit function gets the next
- * 8 byte packet and initiates a CAN transmit on the appropriate CAN channel.
- * @details Inputs: Output CAN Comm Buffer(s)
- * @details Outputs: none
- * @return buffer with highest priority CAN packet to transmit,
- * COMM_BUFFER_NOT_USED if not CAN packets pending transmit found
+ * The findNextHighestPriorityCANPacketToTransmit function determines which
+ * outgoing buffer with data in it has the highest priority.
+ * @details \b Inputs: Outgoing CAN buffer
+ * @details \b Outputs: none
+ * @return Highest priority CAN buffer with data to transmit,
+ * COMM_BUFFER_NOT_USED if there is no data to be transmitted.
  *************************************************************************/
 static COMM_BUFFER_T findNextHighestPriorityCANPacketToTransmit( void )
 {
@@ -325,11 +336,14 @@
 
 /*********************************************************************//**
  * @brief
- * The transmitNextCANPacket function gets the next 8 byte packet and initiates
- * a CAN transmit on the appropriate CAN channel.
- * @details Inputs: Output CAN Comm Buffers
- * @details Outputs: CAN packet transmit initiated.
- * @return number of bytes transmitted
+ * The transmitNextCANPacket function creates a frame from the next 8 bytes
+ * to transmit (if there is data to transmit) and initiates a CAN transmit
+ * on the appropriate CAN channel.
+ * @details \b Alarm: ALARM_ID_TD_SOFTWARE_FAULT if invalid byte count or
+ * if frame transmit fails.
+ * @details \b Inputs: Output CAN buffers
+ * @details \b Outputs: none
+ * @return number of bytes transmitted (8 or 0)
  *************************************************************************/
 static U32 transmitNextCANPacket( void )
 {
@@ -379,11 +393,10 @@
 
 /*********************************************************************//**
  * @brief
- * The processIncomingData function parses out messages from the Input
- * Comm Buffers and adds them to the Received Message Queue.
- * @details Inputs: none
- * @details Outputs: rcvMsg, dgIsCommunicating,
- * timeOfLastDGCheckIn, timeOfLastUICheckIn, uiDidCommunicate
+ * The processIncomingData function parses out messages from the incoming
+ * CAN buffers and adds them to the Received Message Queue.
+ * @details \b Inputs: none
+ * @details \b Outputs: canXmitRetryCtr
  * @return none
  *************************************************************************/
 static void processIncomingData( void )
@@ -472,10 +485,11 @@
 /*********************************************************************//**
  * @brief
  * The consumeBufferPaddingBeforeSync function removes any bytes in a given
- * buffer that lie before a sync byte.
- * @details Inputs: none
- * @details Outputs: Any padding at front of buffer is consumed.
- * @param buffer the comm buffer to process
+ * buffer that lie before a sync byte to re-sync with the data.
+ * @details \b Inputs: none
+ * @details \b Outputs: Any bytes in buffers preceding a sync byte at front
+ * of buffer is consumed.
+ * @param buffer the CAN buffer to re-sync
  * @return none
  *************************************************************************/
 static void consumeBufferPaddingBeforeSync( COMM_BUFFER_T buffer )
@@ -502,13 +516,17 @@
 /*********************************************************************//**
  * @brief
  * The parseMessageFromBuffer function looks for a complete message in a
- * given buffer.  If a message is found, its size is returned.
- * @details Inputs: none
- * @details Outputs: none
- * @param data pointer to byte array to search for a message
+ * buffer (pointed to by given data pointer).  If a message is found, its
+ * size is returned.
+ * @note The message is not consumed (removed) from the buffer.  Calling
+ * function is expected to retrieve the message by consuming the returned
+ * message size from the given buffer.
+ * @details \b Inputs: none
+ * @details \b Outputs: none
+ * @param data pointer to start of a CAN buffer to search for a message in
  * @param len number of bytes in the data to search
- * @return size of message if found, zero if no complete message found,
- * -1 if message found but CRC fails.
+ * @return The size of the message, if found, zero if no complete message
+ * is found, -1 if message found but CRC fails.
  *************************************************************************/
 static S32 parseMessageFromBuffer( U08 *data, U32 len )
 {