added function documentation

src/shellmatta_ymodem.c

@@ -84,6 +84,12 @@ static void shellmatta_ymodem_reset(shellmatta_handle_t handle, bool doCancel)
     (void)memset((void *)&inst->ymodem.packet, 0, sizeof(shellmatta_ymodem_packet_t));
 }
 
+/**
+ * @brief                   Processes a completely received ymodem packet
+ * @param[in, out]  handle  shellmatta instance handle
+ * @return      errorcode   #SHELLMATTA_OK
+ *                          #SHELLMATTA_ERROR (invalid file size)
+*/
 shellmatta_retCode_t processPacket(shellmatta_handle_t handle)
 {
     shellmatta_retCode_t ret = SHELLMATTA_OK;
@@ -123,6 +129,13 @@ shellmatta_retCode_t processPacket(shellmatta_handle_t handle)
     return ret;
 }
 
+/**
+ * @brief                   Processes incoming bytes using the ymodem state machine
+ * @param[in, out]  handle  shellmatta instance handle
+ * @param[in]       byte    received byte
+ * @return      errorcode   #SHELLMATTA_OK
+ *                          #SHELLMATTA_ERROR (error during packet processing)
+*/
 static shellmatta_retCode_t ymodem_stateMachine(shellmatta_handle_t handle, uint8_t byte)
 {
     shellmatta_retCode_t ret = SHELLMATTA_OK;
@@ -258,6 +271,13 @@ static shellmatta_retCode_t ymodem_stateMachine(shellmatta_handle_t handle, uint
     return ret;
 }
 
+/**
+ * @brief                   Processes incoming bytes - checking for cancel requests and calling the state machine
+ * @param[in, out]  handle  shellmatta instance handle
+ * @param[in]       byte    received byte
+ * @return      errorcode   #SHELLMATTA_OK
+ *                          #SHELLMATTA_ERROR (error during packet processing)
+*/
 shellmatta_retCode_t shellmatta_ymodem_processByte(shellmatta_handle_t handle, char byte)
 {
     shellmatta_instance_t *inst = (shellmatta_instance_t*)handle;
@@ -288,6 +308,13 @@ shellmatta_retCode_t shellmatta_ymodem_processByte(shellmatta_handle_t handle, c
     return ret;
 }
 
+/**
+ * @brief                   Processes a poll from the application without data - shall be calles every second when
+ *                          no data is received
+ * @param[in, out]  handle  shellmatta instance handle
+ * @return      errorcode   #SHELLMATTA_OK
+ *                          #SHELLMATTA_ERROR (error during packet processing)
+*/
 shellmatta_retCode_t shellmatta_ymodem_poll(shellmatta_handle_t handle)
 {
     shellmatta_retCode_t ret = SHELLMATTA_ERROR;
@@ -338,12 +365,13 @@ shellmatta_retCode_t shellmatta_ymodem_poll(shellmatta_handle_t handle)
  * @brief                                           Initialise the ymodem prior to actually receiving data
  * @param[in, out]  handle                          shellmatta instance handle
  * @param[in]       recvBuffer                      pointer to the buffer to save the received payload in
- * @param[in]       recvPacketCallback              pointer to the file size variable
- * @param[in]       recvPacketCallback              pointer to the packet size variable
- * @param[in]       transmissionCompleteCallback    callback functions for the ymodem module
+ * @param[in]       cancelCallback                  callback function for transmission being canceled
+ * @param[in]       recvHeaderCallback              callback function for header received
+ * @param[in]       recvPacketCallback              callback function for data packet received
+ * @param[in]       transmissionCompleteCallback    callback function for transmission complete
  * @return          errorcode   #SHELLMATTA_OK
  *                              #SHELLMATTA_USE_FAULT (param err)
- * @note            Disables the tranport layer if inactive or sets it to mandatory if active
+ * @note            Forces the transport layer in a fixed state when not mandatory
 */
 shellmatta_retCode_t shellmatta_ymodem_init(shellmatta_handle_t             handle,
                                             uint8_t*                        recvBuffer,
@@ -469,10 +497,11 @@ shellmatta_retCode_t shellmatta_ymodem_resume(shellmatta_handle_t handle)
 
 /**
  * @brief                   Resets the ymodem module
+ * @param[in, out]  handle  shellmatta instance handle
  * @param[in]   doCancel    Set this flag to execute the cancel-callback function within the ymodem-reset function
  * @return      errorcode   #SHELLMATTA_OK
  *                          #SHELLMATTA_USE_FAULT (param err)
- * @note                    call this function after file transmission is done or cancelled
+ * @note                    call this function to cancel an ongoing transmission
 */
 shellmatta_retCode_t shellmatta_ymodem_cancel(shellmatta_handle_t handle, bool doCancel)
 {
@@ -484,7 +513,7 @@ shellmatta_retCode_t shellmatta_ymodem_cancel(shellmatta_handle_t handle, bool d
         &&  (SHELLMATTA_MAGIC   == inst->magic))
     {
         shellmatta_ymodem_reset(handle, doCancel);
-        /* clear any possibly leftover inputs */
+        /* clear any possible leftover inputs */
         utils_clearInput((shellmatta_instance_t*)handle);
     }
     else