ESP8266WiFi - document event handler lifetime, add [[nodiscard]] (#9087)

* disallow not assigning wifieventhandler somewhere

* fix markdown syntax in rst

* mention lifetime in example and docs

doc/esp8266wifi/generic-examples.rst

@@ -38,16 +38,29 @@ Register the Events
 
 To get events to work we need to complete just two steps:
 
-1. Declare the event handler:
+1. Declare the event handler in global scope.
 
-``cpp   WiFiEventHandler disconnectedEventHandler;``
+.. code:: cpp
+    WiFiEventHandler disconnectedEventHandler;
 
-2. Select particular event (in this case ``onStationModeDisconnected``)
-   and add the code to be executed when event is fired.
+Alternatively, it can be declared as ``static`` in both function and global scopes.
 
-``cpp   disconnectedEventHandler = WiFi.onStationModeDisconnected([](const WiFiEventStationModeDisconnected& event)   {     Serial.println("Station disconnected");   });`` If this event is fired the code will print out information that station has been disconnected.
 
-That's it. It is all we need to do.
+2. Select particular event (in this case ``onStationModeDisconnected``).
+   When this event is fired the code will print out information that station has been disconnected:
+
+.. code:: cpp
+    disconnectedEventHandler = WiFi.onStationModeDisconnected(
+        [](auto&& event) {
+            Serial.println("Station disconnected");
+        });
+
+3. Disable ``disconnectedEventHandler``, so the event is no longer handled by our callback:
+
+.. code:: cpp
+    disconnectedEventHandler = nullptr;
+
+Take note that lifetime of the callback handler is up to the app. e.g. if ``onStationModeDisconnected`` is declared in the function scope, it would be discarded immediately after the function exists.
 
 The Code
 ~~~~~~~~

doc/esp8266wifi/soft-access-point-examples.rst

@@ -79,7 +79,9 @@ Sketch is small so analysis shouldn't be difficult. In first line we are includi
 
 Setting up of the access point ``ESPsoftAP_01`` is done by executing:
 
-``cpp  boolean result = WiFi.softAP("ESPsoftAP_01", "pass-to-soft-AP");``
+.. code:: cpp
+
+    boolean result = WiFi.softAP("ESPsoftAP_01", "pass-to-soft-AP");
 
 If this operation is successful then ``result`` will be ``true`` or ``false`` if otherwise. Basing on that either ``Ready`` or ``Failed!`` will be printed out by the following ``if - else`` conditional statement.
 

libraries/ESP8266WiFi/examples/WiFiEvents/WiFiEvents.ino

@@ -24,6 +24,9 @@
 const char* ssid = APSSID;
 const char* password = APPSK;
 
+// WiFi.on* methods **must** only be called **after** entering setup().
+// Assigning immediately in global scope is not adviced, neither is assigning them within any other object constructors.
+// These variables **may** exist in function block, but **only** if they are declared as `static`
 WiFiEventHandler stationConnectedHandler;
 WiFiEventHandler stationDisconnectedHandler;
 WiFiEventHandler probeRequestPrintHandler;
@@ -43,12 +46,12 @@ void setup() {
   WiFi.mode(WIFI_AP);
   WiFi.softAP(ssid, password);
 
-  // Register event handlers.
-  // Callback functions will be called as long as these handler objects exist.
   // Call "onStationConnected" each time a station connects
   stationConnectedHandler = WiFi.onSoftAPModeStationConnected(&onStationConnected);
+
   // Call "onStationDisconnected" each time a station disconnects
   stationDisconnectedHandler = WiFi.onSoftAPModeStationDisconnected(&onStationDisconnected);
+
   // Call "onProbeRequestPrint" and "onProbeRequestBlink" each time
   // a probe request is received.
   // Former will print MAC address of the station and RSSI to Serial,

libraries/ESP8266WiFi/src/ESP8266WiFiGeneric.h

@@ -71,15 +71,15 @@ class ESP8266WiFiGenericClass {
         void onEvent(WiFiEventCb cb, WiFiEvent_t event = WIFI_EVENT_ANY) __attribute__((deprecated));
 
         // Subscribe to specific event and get event information as an argument to the callback
-        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 onSoftAPModeProbeRequestReceived(std::function<void(const WiFiEventSoftAPModeProbeRequestReceived&)>);
-        WiFiEventHandler onWiFiModeChange(std::function<void(const WiFiEventModeChange&)>);
+        [[nodiscard]] WiFiEventHandler onStationModeConnected(std::function<void(const WiFiEventStationModeConnected&)>);
+        [[nodiscard]] WiFiEventHandler onStationModeDisconnected(std::function<void(const WiFiEventStationModeDisconnected&)>);
+        [[nodiscard]] WiFiEventHandler onStationModeAuthModeChanged(std::function<void(const WiFiEventStationModeAuthModeChanged&)>);
+        [[nodiscard]] WiFiEventHandler onStationModeGotIP(std::function<void(const WiFiEventStationModeGotIP&)>);
+        [[nodiscard]] WiFiEventHandler onStationModeDHCPTimeout(std::function<void(void)>);
+        [[nodiscard]] WiFiEventHandler onSoftAPModeStationConnected(std::function<void(const WiFiEventSoftAPModeStationConnected&)>);
+        [[nodiscard]] WiFiEventHandler onSoftAPModeStationDisconnected(std::function<void(const WiFiEventSoftAPModeStationDisconnected&)>);
+        [[nodiscard]] WiFiEventHandler onSoftAPModeProbeRequestReceived(std::function<void(const WiFiEventSoftAPModeProbeRequestReceived&)>);
+        [[nodiscard]] WiFiEventHandler onWiFiModeChange(std::function<void(const WiFiEventModeChange&)>);
 
         uint8_t channel(void);