Completed the documentation of the communication module.

It needs to be reviewed.

comm/include/comm.h

@@ -51,7 +51,7 @@ typedef enum {COMM_SUCCESS=0x00,/*!< The communication module has ended successf
  *
  * ![](tx_irq_driven.png)
  *
- * The user application starts a TX driven transmission by calling the comm_send_irq()
+ * The user application starts a IRQ driven transmission by calling the comm_send_irq()
  * function, which in turn calls the low level communication function pointed by
  * the parameter send_irq. At this point the interrupt handler is called each time 
  * a byte is actually sent, which calls the comm_do_irq_send() function to update
@@ -79,7 +79,50 @@ typedef enum {COMM_SUCCESS=0x00,/*!< The communication module has ended successf
  * turn, calls the user callback function pointed by irq_receive_cb. The reception 
  * remains active until the desired number of bytes are received, or the user 
  * application cancels it.
+ * 
+ * To get the received data, use the comm_get_received_data() function.
+ *
+ * The following diagram descrives the transmission operation when using 
+ * DMA, and how the user application, the communication module and the
+ * actual communication device work together:
+ *
+ * ![](tx_dma_driven.png)
+ *
+ * The user application starts a DMA driven transmission by calling the comm_send_dma()
+ * function, which in turn calls the low level communication function pointed by
+ * the parameter send_dma. This function should configure the DMA transfer and start 
+ * it.
+ * 
+ * When the last byte to be transmitted is written to the communication device,
+ * the DMA interrupt handler is called, which calls the comm_do_dma_send()
+ * function which enables the TX interrupts to wait until the last byte has
+ * been actually sent.
+ * 
+ * Finally, when the TX interrupt handler is called, the comm_do_irq_send()
+ * function is called, in the same way it is called in a regular IRQ driven
+ * transmission. In this case however, its behaviour is different, because 
+ * the user application callback function pointed by dma_send_cb is called,
+ * so that the user can perform any required action.
  *
+ * The following diagram descrives the reception operation when using 
+ * DMA, and how the user application, the communication module and the
+ * actual communication device work together:
+ *
+ * ![](rx_dma_driven.png)
+ *
+ * The user application starts a DMA driven reception by calling the comm_recive_dma()
+ * function, which in turn calls the low level communication function pointed by
+ * the parameter receive_dma. This function should configure the DMA transfer and start 
+ * it.
+ * 
+ * When the desired number of bytes have been received, the reception DMA interrupt
+ * handler is called, which calls the comm_do_dma_receive() function, calls the
+ * user application function pointed by the dma_receive_cb parameter, so that the
+ * user canm perform any required action.
+ * 
+ * In the case of DMA driven reception, the received data can be accessed by the 
+ * data pointer provided to the comm_recive_dma() function, once the reception 
+ * has ended.
  */
 typedef struct
 {
@@ -403,7 +446,7 @@ comm_error comm_receive(TComm *dev,unsigned char *data,unsigned short int *lengt
 /** 
  * \brief Function to start an interrupt driven transmission
  * 
- * This function is used to start a reception in IRQ driven mode. This function
+ * This function is used to start a transmission in IRQ driven mode. This function
  * starts sending the data but returns immediatelly, reporting an error, if any.
  * The data in the input parameter is copied to the internal buffer before it 
  * returns.
@@ -435,73 +478,248 @@ comm_error comm_send_irq(TComm *dev,unsigned char *data,unsigned short int lengt
  * transfer, this function calls the corresponding IRQ transmission callback 
  * function. When the last byte has been sent, this function automatically stops
  * the current transmission, and returns a value of 0x00 to report it.
+ * 
+ * The interrupt handler should use the value returned by this function to send
+ * the next byte or disable the transmission interrupts when the transmission
+ * is finished (in either case).
+ *
+ * Use the comm_get_error() function to get any possible error that happen 
+ * during transmission.
+ * 
+ * \param dev pointer to a valid TComm structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable. 
+ * \param byte this parameter holds the value to be sent next when the function
+ *        returns 0x00, when it is part of an IRQ driven transmission. Otherwise
+ *        this parameter must be ignored.
+ *
+ * \return 0x00 when the transmission has ended and any other value when there
+ *         are still some bytes to be sent.
  */
 unsigned char comm_do_irq_send(TComm *dev,unsigned char *byte);
 /** 
  * \brief Function to start an interrupt driven reception
  * 
+ * This function is used to start a reception in IRQ driven mode. This function
+ * starts the reception process but returns immediatelly, reporting an error, if any.
+ * The received data is stored into the internal buffer, and the comm_get_received_data()
+ * function should be used to get it.
+ * 
+ * This function calls the function of the low level communication module pointed
+ * by the receive_irq parameter.
+ * 
+ * \param dev pointer to a valid TComm structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable. 
+ * \param length Number of bytes to be transmitted.
+ *
+ * \return the status of the reception. The possible values are the elements
+ *         in the comm_error ennumeraiton. 
+
  */
 comm_error comm_receive_irq(TComm *dev,unsigned short int length);
 /** 
  * \brief Function to handle the reception of a single byte
- * 
+ *
+ * This function should be called from the interrupt handler each time a byte has
+ * been received. When this function is called, it first call the user defined
+ * function pointed by the irq_receive_cb parameter to check the receoved data 
+ * (if necessary).
+ *
+ * If the callback function returns 0x00, the received byte is ignored and
+ * the reception process continues. If the callback function returns any other
+ * value, the new byte is stored into the internal buffer until all the desired
+ * bytes have been received.
+ *
+ * \param dev pointer to a valid TComm structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable. 
+ * \param byte this parameter holds the last byte that has been received through
+ *        the communication device, and it is passed to the user callback in order 
+ *        to be processed. 
+ *
+ * \return 0x00 when the reception has ended and any other value when there
+ *         are still some bytes to be received.
  */
 unsigned char comm_do_irq_receive(TComm *dev,unsigned char byte);
 /** 
  * \brief Function to get the received data
- * 
+ *
+ * This function is used to get the data received by an IRQ driven reception.
+ * This function can only be called when the reception has ended, otherwise it
+ * reports a busy error.
+ *
+ * Use the comm_get_error() function to get any possible error that happen 
+ * during reception.
+ *  
+ * \param dev pointer to a valid TComm structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable. 
+ * \param data buffer where the received data will be copied to be used by the
+ *        user application. The memory for this vector must be pre-allocated
+ *        before calling this function.
+ * \param length is the number of data actually received. In case of no error,
+ *        this value must coincide with the desired value, but it can be less
+ *        in case of any error.
+ *
+ * \return COMM_SUCCESS in case the reception process has ended, and COMM_BUSY
+ *         otherwise.
  */
 comm_error comm_get_received_data(TComm *dev,unsigned char *data,unsigned short int *length);
 /** 
  * \brief Function to cancel the current interrupt driven reception
- * 
+ *
+ * This function cancels any active IRQ driven reception. This function calls the 
+ * function of the low level communication module pointed by the cancel_receive_irq 
+ * parameter to actually stop and disable the reception interrupts.
+ *  
+ * \param dev pointer to a valid TComm structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable. 
  */
 void comm_cancel_irq_receive(TComm *dev);
 /* DMA functions */
 /** 
  * \brief Function to start a DMA driven transmission
  * 
+ * This function is used to start a transmission using DMA. This function calls the
+ * low level communication module pointed by the send_dma parameter. This function
+ * should configure the DMA transaction with the provided information and start it.
+ *
+ * \param dev pointer to a valid TComm structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable. 
+ * \param data pointer to a vector where the data to be transmitted is stored. 
+ *        Memory for this parameter must be pre-allocated before calling this 
+ *        function to avoid unexpected behaviour.
+ * \param length Number of bytes to be transmitted.
+ *
+ * \return COMM_SUCCESS if the transmission has started successfully or COMM_BUSY
+ *         if there is an operation in progress.
  */
 comm_error comm_send_dma(TComm *dev,unsigned char *data,unsigned short int length);
 /** 
  * \brief Function to handle the transmission of all bytes
  * 
+ * This function is called when the last data byte has been sent to the
+ * communication device. This function enables the TX interrupts to actually
+ * wait until the last byte has been sent to avoid possible errors.
+ * 
+ * It is not until the last byte has been actually sent, that the user application
+ * callback function pointed by the dma_send_cb parameter is called. This function
+ * should handle any required action after the transmission.
+ *
+ * \param dev pointer to a valid TComm structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable. 
  */
 void comm_do_dma_send(TComm *dev);
 /** 
  * \brief Function to start a DMA driven reception
  * 
+ * This function is used to start a reception using DMA. This function calls the
+ * low level communication module pointed by the receive_dma parameter. This function
+ * should configure the DMA transaction with the provided information and start it.
+ *
+ * \param dev pointer to a valid TComm structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable. 
+ * \param data pointer to a vector where the received data will be stored. 
+ *        Memory for this parameter must be pre-allocated before calling this 
+ *        function to avoid unexpected behaviour. The contents of this vector
+ *        are not valid until the operation has ended.
+ * \param length Number of bytes to be received.
+ *
+ * \return COMM_SUCCESS if the reception has started successfully or COMM_BUSY
+ *         if there is an operation in progress.
  */
 comm_error comm_receive_dma(TComm *dev,unsigned char *data,unsigned short int length);
 /** 
  * \brief Function to handle the reception of all desired bytes
  * 
+ * This function is called when the last data byte has been received through 
+ * the communication device. At this point, the user application callback function 
+ * pointed by the dma_receive_cb parameter is called. This function should 
+ * handle any required action after the reception.
+ *
+ * \param dev pointer to a valid TComm structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable. 
  */
 void comm_do_dma_receive(TComm *dev);
 /** 
  * \brief Function to cancel the current DMA driven reception
- * 
+ *
+ * This function is used to cancel any active DMA driven reception by calling 
+ * the low level communication device pointed by cancel_receive_dma. When this 
+ * function is called, the contents of the data vector passed to the comm_send_dma()
+ * function can not be used.
+ *
+ * \param dev pointer to a valid TComm structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable. 
  */
 void comm_cancel_dma_receive(TComm *dev);
 /* common functions */
 /** 
  * \brief Function to check whether the current transmission has ended or not
  * 
+ * This funcion is used to check whether there is an active transmission or
+ * not. In the case the transmission has ended, this function indicates if 
+ * there has been an error or not. In case of an error, use the comm_get_error()
+ * function to get it.
+ * 
+ * \param dev pointer to a valid TComm structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable. 
+ *
+ * \return COMM_BUSY if the transmission is still active, COMM_ERROR if the
+ *         last transmission has ended with an error or COMM_SUCCESS if it
+ *         ended successfully.
  */
 comm_error comm_is_send_done(TComm *dev);
 /** 
  * \brief Function to check whether the current reception has ended or not
  * 
+ * This funcion is used to check whether there is an active reception or
+ * not. In the case the reception has ended, this function indicates if 
+ * there has been an error or not. In case of an error, use the comm_get_error()
+ * function to get it.
+ * 
+ * \param dev pointer to a valid TComm structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable. 
+ *
+ * \return COMM_BUSY if the reception is still active, COMM_ERROR if the
+ *         last reception has ended with an error or COMM_SUCCESS if it
+ *         ended successfully.
  */
 comm_error comm_is_receive_done(TComm *dev);
 /** 
  * \brief Function to get the communication error
  * 
+ * This function returns the error of the last transmission or reception 
+ * operation. 
+ * 
+ * \param dev pointer to a valid TComm structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable. 
+ *
+ * \return the error of the last operation or COMM_BUSY if the operation
+ *         is still in progess.
  */
 inline unsigned char comm_get_error(TComm *dev);
 /** 
  * \brief Function to set the communication error
- * 
+ *
+ * The user application and the low level communications module can use this
+ * function to set the internal communication error at any time. The error
+ * set by this function can be get with the comm_get_error() function.
+ *
+ * \param dev pointer to a valid TComm structure to be initialized. If 
+ *        memory is not pre-allocated before calling this function, its 
+ *        behavior is unpredictable. 
+ * \param error identifier of the error to be set
  */
 inline void comm_set_error(TComm *dev, unsigned char error);