doc: improve WiFi.persistent documentation (#5081)

fixes #3641

doc/esp8266wifi/generic-class.rst

@@ -10,7 +10,7 @@ onEvent
 
 .. code:: cpp
 
-    void  onEvent (WiFiEventCb cb, WiFiEvent_t event=WIFI_EVENT_ANY) __attribute__((deprecated)) 
+    void  onEvent (WiFiEventCb cb, WiFiEvent_t event=WIFI_EVENT_ANY) __attribute__((deprecated))
 
 To see how to use ``onEvent`` please check example sketch `WiFiClientEvents.ino <https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/WiFiClientEvents/WiFiClientEvents.ino>`__ available inside examples folder of the ESP8266WiFi library.
 
@@ -19,13 +19,13 @@ WiFiEventHandler
 
 .. code:: cpp
 
-    WiFiEventHandler  onStationModeConnected (std::function< void(const WiFiEventStationModeConnected &)>) 
-    WiFiEventHandler  onStationModeDisconnected (std::function< void(const WiFiEventStationModeDisconnected &)>) 
-    WiFiEventHandler  onStationModeAuthModeChanged (std::function< void(const WiFiEventStationModeAuthModeChanged &)>) 
-    WiFiEventHandler  onStationModeGotIP (std::function< void(const WiFiEventStationModeGotIP &)>) 
-    WiFiEventHandler  onStationModeDHCPTimeout (std::function< void(void)>) 
-    WiFiEventHandler  onSoftAPModeStationConnected (std::function< void(const WiFiEventSoftAPModeStationConnected &)>) 
-    WiFiEventHandler  onSoftAPModeStationDisconnected (std::function< void(const WiFiEventSoftAPModeStationDisconnected &)>) 
+    WiFiEventHandler  onStationModeConnected (std::function< void(const WiFiEventStationModeConnected &)>)
+    WiFiEventHandler  onStationModeDisconnected (std::function< void(const WiFiEventStationModeDisconnected &)>)
+    WiFiEventHandler  onStationModeAuthModeChanged (std::function< void(const WiFiEventStationModeAuthModeChanged &)>)
+    WiFiEventHandler  onStationModeGotIP (std::function< void(const WiFiEventStationModeGotIP &)>)
+    WiFiEventHandler  onStationModeDHCPTimeout (std::function< void(void)>)
+    WiFiEventHandler  onSoftAPModeStationConnected (std::function< void(const WiFiEventSoftAPModeStationConnected &)>)
+    WiFiEventHandler  onSoftAPModeStationDisconnected (std::function< void(const WiFiEventSoftAPModeStationDisconnected &)>)
 
 To see a sample application with ``WiFiEventHandler``, please check separate section with `examples :arrow\_right: <generic-examples.rst>`__ dedicated specifically to the Generic Class..
 
@@ -34,25 +34,21 @@ persistent
 
 .. code:: cpp
 
-    WiFi.persistent (persistent) 
+    WiFi.persistent(persistent)
 
-Module is able to reconnect to last used Wi-Fi network on power up or reset basing on settings stored in specific sectors of flash memory. By default these settings are written to flash each time they are used in functions like ``WiFi.begin(ssid, password)``. This happens no matter if SSID or password has been actually changed.
+ESP8266 is able to reconnect to the last used Wi-Fi network or establishes the same Access Point upon power up or reset.
+By default, these settings are written to specific sectors of flash memory every time they are changed in ``WiFi.begin(ssid, passphrase)`` or ``WiFi.softAP(ssid, passphrase, channel)``, and when ``WiFi.disconnect`` or ``WiFi.softAPdisconnect`` is invoked.
+Frequently calling these functions could cause wear on the flash memory (see issue `#1054 <https://github.com/esp8266/Arduino/issues/1054>`__).
 
-This might result in some wear of flash memory depending on how often such functions are called.
-
-Setting ``persistent`` to ``false`` will get SSID / password written to flash only if currently used values do not match what is already stored in flash.
-
-Please note that functions ``WiFi.disconnect`` or ``WiFi.softAPdisconnect`` reset currently used SSID / password. If ``persistent`` is set to ``false``, then using these functions will not affect SSID / password stored in flash.
-
-To learn more about this functionality, and why it has been introduced, check issue report `#1054 <https://github.com/esp8266/Arduino/issues/1054>`__.
+Once ``WiFi.persistent(false)`` is called, ``WiFi.begin``, ``WiFi.disconnect``, ``WiFi.softAP``, or ``WiFi.softAPdisconnect`` only changes the current in-memory Wi-Fi settings, and does not affect the Wi-Fi settings stored in flash memory.
 
 mode
 ~~~~
 
 .. code:: cpp
 
-    WiFi.mode(m) 
-    WiFi.getMode() 
+    WiFi.mode(m)
+    WiFi.getMode()
 
 -  ``WiFi.mode(m)``: set mode to ``WIFI_AP``, ``WIFI_STA``,
    ``WIFI_AP_STA`` or ``WIFI_OFF``
@@ -64,17 +60,17 @@ Other Function Calls
 
 .. code:: cpp
 
-    int32_t  channel (void) 
-    bool  setSleepMode (WiFiSleepType_t type) 
-    WiFiSleepType_t  getSleepMode () 
-    bool  setPhyMode (WiFiPhyMode_t mode) 
-    WiFiPhyMode_t  getPhyMode () 
-    void  setOutputPower (float dBm) 
-    WiFiMode_t  getMode () 
-    bool  enableSTA (bool enable) 
-    bool  enableAP (bool enable) 
-    bool  forceSleepBegin (uint32 sleepUs=0) 
-    bool  forceSleepWake () 
+    int32_t  channel (void)
+    bool  setSleepMode (WiFiSleepType_t type)
+    WiFiSleepType_t  getSleepMode ()
+    bool  setPhyMode (WiFiPhyMode_t mode)
+    WiFiPhyMode_t  getPhyMode ()
+    void  setOutputPower (float dBm)
+    WiFiMode_t  getMode ()
+    bool  enableSTA (bool enable)
+    bool  enableAP (bool enable)
+    bool  forceSleepBegin (uint32 sleepUs=0)
+    bool  forceSleepWake ()
     int  hostByName (const char *aHostname, IPAddress &aResult)
 
 Documentation for the above functions is not yet prepared.