cleanup comments

Author: mhightower83

bootloaders/eboot/eboot.c

@@ -32,8 +32,8 @@
   ets_wdt_* APIs, so our choices are not too critical.
   The SDK will set up the WDT as it wants it.
 
-  A rationale for keeping the ets_wdt_enable() line. If the system is not stable
-  during a "soft restart." The HWDT would provide a recovery reboot.
+  A rationale for keeping the "ets_wdt_enable()" line, if the system is not
+  stable during a "soft restart," the HWDT would provide a recovery reboot.
 */
 extern void ets_wdt_enable(uint32_t mode, uint32_t arg1, uint32_t arg2);
 /*
@@ -44,10 +44,10 @@ extern void ets_wdt_enable(uint32_t mode, uint32_t arg1, uint32_t arg2);
   For current mode 1, calls ets_timer_disarm, then return the current mode.
   For current mode 2, calls ets_isr_mask, then return the current mode.
 
-  I always see a value of 0xFFFFFFFF.
+  I always see a return value of 0xFFFFFFFF.
 
-  The value would normally be used with ets_wdt_restore; however, that is not an
-  option since a valid prior call to ets_wdt_enable() may not have been done.
+  The return value would normally be used with ets_wdt_restore; however, that is
+  not an option since a valid prior call to ets_wdt_enable() may not have been done.
 */
 extern uint32_t ets_wdt_disable(void);
 

cores/esp8266/Esp.cpp

@@ -533,9 +533,11 @@ bool EspClass::eraseConfig(void) {
 }
 
 bool EspClass::eraseConfigAndReset(void) {
+    // Before calling, ensure the WiFi state is equivalent to
+    // "WiFi.mode(WIFI_OFF)." This will reduce the likelihood of the SDK
+    // performing WiFi data writes to Flash between erasing and resetting.
     bool reset = eraseConfig();
     if (reset) {
-        // Must be called in WiFi.mode(WIFI_OFF) state.
         hardware_reset();
     }
     return reset;

cores/esp8266/Esp.h

@@ -212,19 +212,20 @@ class EspClass {
 
         static bool eraseConfig();
 
-        /*
-        Erases 4 sectors at the end of flash, 1 - RF_CAL and 3 - SYSTEMPARM.
-        These are the same additional sectors that are erase when you select
-        Erase Flash: "Sketch + WiFi Settings" from the Arduino IDE Tools menu.
-
-        As a precaution, since this operation erases the running SDKs flash
-        configuration space, use reset flag "true" with eraseConfig. Also, for
-        additional protection, call "WiFi.mode(WIFI_OFF)" before calling.
-
-        If you need to erase "WiFi Settings" and reboot consider using
-        "ArduinoOTA.eraseConfigAndReset()" it handles shutting down WiFi
-        before the erase.
-        */
+        /**
+         * @brief Erases 4 sectors at the end of flash, 1 - RF_CAL and 3 - SYSTEMPARM.
+         * These are the same additional sectors that are erase when you select
+         * Erase Flash: "Sketch + WiFi Settings" from the Arduino IDE Tools menu.
+         *
+         * This operation erases the running SDK's flash configuration space.
+         * As a precaution before calling, first call "WiFi.mode(WIFI_OFF)."
+         *
+         * If you need to erase "WiFi Settings" and reboot consider using
+         * "ArduinoOTA.eraseConfigAndReset()" it handles shutting down WiFi
+         * before the erase.
+         * @return bool result of operation. Always False on return.
+         * Function does not return on success.
+         */
         static bool eraseConfigAndReset();
 
         static uint8_t *random(uint8_t *resultArray, const size_t outputSizeBytes);