diff --git a/comm/include/comm.h b/comm/include/comm.h
index c6ca16db0f5509e672ac3199c464dd8969b28533..c8cc9e439c9931f6208d360ffb9bb96a23918f58 100644
--- a/comm/include/comm.h
+++ b/comm/include/comm.h
@@ -51,7 +51,7 @@ typedef enum {COMM_SUCCESS=0x00,/*!< The communication module has ended successf
*
* 
*
- * 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:
+ *
+ * 
+ *
+ * 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:
+ *
+ * 
+ *
+ * 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);