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.