Add/unify comments for target and source sites of async scheduling via delay()/esp_yield()/esp_schedule() (#6780)

Author: dok-net

libraries/ESP8266WiFi/src/ESP8266WiFiGeneric.cpp

@@ -623,6 +623,7 @@ int ESP8266WiFiGenericClass::hostByName(const char* aHostname, IPAddress& aResul
     } else if(err == ERR_INPROGRESS) {
         _dns_lookup_pending = true;
         delay(timeout_ms);
+        // will resume on timeout or when wifi_dns_found_callback fires
         _dns_lookup_pending = false;
         // will return here when dns_found_callback fires
         if(aResult.isSet()) {
@@ -654,7 +655,7 @@ void wifi_dns_found_callback(const char *name, CONST ip_addr_t *ipaddr, void *ca
     if(ipaddr) {
         (*reinterpret_cast<IPAddress*>(callback_arg)) = IPAddress(ipaddr);
     }
-    esp_schedule(); // resume the hostByName function
+    esp_schedule(); // break delay in hostByName
 }
 
 uint32_t ESP8266WiFiGenericClass::shutdownCRC (const WiFiState* state)

libraries/ESP8266WiFi/src/ESP8266WiFiSTA-WPS.cpp

@@ -71,7 +71,7 @@ bool ESP8266WiFiSTAClass::beginWPSConfig(void) {
     }
 
     esp_yield();
-    // will return here when wifi_wps_status_cb fires
+    // will resume when wifi_wps_status_cb fires
 
     return true;
 }
@@ -107,5 +107,5 @@ void wifi_wps_status_cb(wps_cb_status status) {
     }
     // TODO user function to get status
 
-    esp_schedule(); // resume the beginWPSConfig function
+    esp_schedule(); // resume beginWPSConfig
 }

libraries/ESP8266WiFi/src/ESP8266WiFiScan.cpp

@@ -98,7 +98,7 @@ int8_t ESP8266WiFiScanClass::scanNetworks(bool async, bool show_hidden, uint8 ch
             return WIFI_SCAN_RUNNING;
         }
 
-        esp_yield();
+        esp_yield(); // will resume when _scanDone fires
         return ESP8266WiFiScanClass::_scanCount;
     } else {
         return WIFI_SCAN_FAILED;
@@ -323,7 +323,7 @@ void ESP8266WiFiScanClass::_scanDone(void* result, int status) {
     ESP8266WiFiScanClass::_scanComplete = true;
 
     if(!ESP8266WiFiScanClass::_scanAsync) {
-        esp_schedule();
+        esp_schedule(); // resume scanNetworks
     } else if (ESP8266WiFiScanClass::_onComplete) {
         ESP8266WiFiScanClass::_onComplete(ESP8266WiFiScanClass::_scanCount);
         ESP8266WiFiScanClass::_onComplete = nullptr;

libraries/ESP8266WiFi/src/include/ClientContext.h

@@ -130,10 +130,10 @@ class ClientContext
         }
         _connect_pending = true;
         _op_start_time = millis();
-        // Following delay will be interrupted by connect callback
         for (decltype(_timeout_ms) i = 0; _connect_pending && i < _timeout_ms; i++) {
                // Give scheduled functions a chance to run (e.g. Ethernet uses recurrent)
                delay(1);
+               // will resume on timeout or when _connected or _notify_error fires
         }
         _connect_pending = false;
         if (!_pcb) {
@@ -435,7 +435,7 @@ class ClientContext
         if (_connect_pending || _send_waiting) {
             _send_waiting = false;
             _connect_pending = false;
-            esp_schedule(); // break current delay()
+            esp_schedule(); // break delay in connect or _write_from_source
         }
     }
 
@@ -461,10 +461,11 @@ class ClientContext
             }
 
             _send_waiting = true;
-            // Following delay will be interrupted by on next received ack
             for (decltype(_timeout_ms) i = 0; _send_waiting && i < _timeout_ms; i++) {
                // Give scheduled functions a chance to run (e.g. Ethernet uses recurrent)
                delay(1);
+               // will resume on timeout or when _write_some_from_cb or _notify_error fires
+
             }
             _send_waiting = false;
         } while(true);
@@ -536,7 +537,7 @@ class ClientContext
     {
         if (_send_waiting) {
             _send_waiting = false;
-            esp_schedule(); // break current delay()
+            esp_schedule(); // break delay in _write_from_source
         }
     }
 
@@ -612,7 +613,7 @@ class ClientContext
         assert(pcb == _pcb);
         if (_connect_pending) {
             _connect_pending = false;
-            esp_schedule(); // break current delay()
+            esp_schedule(); // break delay in connect
         }
         return ERR_OK;
     }