Improve source code comments

This commit improves the source code comments in several locations, adding explanations
for things that might easily be misunderstood, or take a long time to understand.

Author: Alrik Vidstrom

src/USBHostMSD/USBHostMSD.cpp

@@ -193,7 +193,8 @@ int USBHostMSD::checkResult(uint8_t res, USBEndpoint * ep)
         return -1;
     }
 
-    // if ep stalled: send clear feature
+    // Notice that USB_TYPE_STALL_ERROR is never actually set anywhere in the library for the ST target, because
+    // URB_STALL is never handled directly. Otherwise, this would be the code to unstall the EP.
     if (res == USB_TYPE_STALL_ERROR) {
         res = host->controlWrite(   dev,
                                     USB_RECIPIENT_ENDPOINT | USB_HOST_TO_DEVICE | USB_REQUEST_TYPE_STANDARD,
@@ -285,7 +286,9 @@ int USBHostMSD::SCSITransfer(uint8_t * cmd, uint8_t cmd_len, int flags, uint8_t
                                     BO_MASS_STORAGE_RESET,
                                     0, msd_intf, NULL, 0);
 
-        // unstall [sic!] both endpoints
+        // Unstall [sic!] both endpoints.
+        // Notice that this is the unstall that is required by the specification as part of clearing a Phase Error,
+        // _not_ the unstall for an ordinarily stalled EP!
         res = host->controlWrite(   dev,
                                     USB_RECIPIENT_ENDPOINT | USB_HOST_TO_DEVICE | USB_REQUEST_TYPE_STANDARD,
                                     CLEAR_FEATURE,

src/targets/TARGET_STM/USBHALHost_STM.cpp

@@ -76,6 +76,21 @@ uint32_t HAL_HCD_HC_GetType(HCD_HandleTypeDef *hhcd, uint8_t chnum)
     return hhcd->hc[chnum].ep_type;
 }
 
+// The urb_state parameter can be one of the following according to the ST documentation, but the explanations
+// that follow are the result of an analysis of the ST HAL / LL source code, the Reference Manual for the
+// STM32H747 microcontroller, and the source code of this library:
+//
+//  - URB_ERROR    = various serious errors that may be hard or impossible to recover from without pulling
+//                   the thumb drive out and putting it back in again, but we will try
+//  - URB_IDLE     = set by a call to HAL_HCD_HC_SubmitRequest(), but never used by this library
+//  - URB_NYET     = never actually used by the ST HAL / LL at the time of writing, nor by this library
+//  - URB_STALL    = a stall response from the device - but it is never handled by the library and will end up
+//                   as a timeout at a higher layer, because of an ep_queue.get() timeout, which will activate
+//                   error recovery indirectly
+//  - URB_DONE     = the transfer completed normally without errrors
+//  - URB_NOTREADY = a NAK, NYET, or not more than a couple of repeats of some of the errors that will
+//                   become URB_ERROR if they repeat several times in a row
+//
 void HAL_HCD_HC_NotifyURBChange_Callback(HCD_HandleTypeDef *hhcd, uint8_t chnum, HCD_URBStateTypeDef urb_state)
 {
     USBHALHost_Private_t *priv = (USBHALHost_Private_t *)(hhcd->pData);
@@ -107,14 +122,11 @@ void HAL_HCD_HC_NotifyURBChange_Callback(HCD_HandleTypeDef *hhcd, uint8_t chnum,
                     }
                     break;
                 case  URB_NOTREADY:
-                    /*  try again  */
-                    /*  abritary limit , to avoid dead lock if other error than
-                     *  slow response is  */
 #if defined(MAX_NOTREADY_RETRY)
                     if (td->retry < MAX_NOTREADY_RETRY) {
-                        /*  increment retry counter */
                         td->retry++;
 #endif
+                        // Submit the same request again, because the device wasn't ready to accept the last one
                         length = td->size <= max_size ? td->size : max_size;
                         HAL_HCD_HC_SubmitRequest(hhcd, chnum, dir, type, !td->setup, (uint8_t *) td->currBufPtr, length, 0);
                         HAL_HCD_EnableInt(hhcd, chnum);
@@ -138,6 +150,9 @@ void HAL_HCD_HC_NotifyURBChange_Callback(HCD_HandleTypeDef *hhcd, uint8_t chnum,
                 td->state = USB_TYPE_IDLE;
             }
             else if (urb_state == URB_ERROR) {
+                // While USB_TYPE_ERROR in the endpoint state is used to activate error recovery, this value is actually never used.
+                // Going here will lead to a timeout at a higher layer, because of ep_queue.get() timeout, which will activate error
+                // recovery indirectly.
                 td->state = USB_TYPE_ERROR;
             } else {
                 td->state = USB_TYPE_PROCESSING;