docs: improve portal guidance and examples

examples/BasicPortal/BasicPortal.ino

@@ -5,8 +5,9 @@ WiFiManager portal;
 
 void setup() {
     Serial.begin(115200);
-    portal.setConfigPortalTimeout(180);
+    portal.setConfigPortalTimeout(180);  // Do not leave a first-boot setup AP open forever.
 
+    // Returns true when saved station credentials connect; otherwise opens the portal.
     if (portal.autoConnect("WiFiManager Basic", "example-pass")) {
         Serial.println("Connected. Run your normal application here.");
     } else {
@@ -14,4 +15,6 @@ void setup() {
     }
 }
 
-void loop() { portal.process(); }
+void loop() {
+    portal.process();  // Keeps DNS, HTTP, and station-recovery work responsive.
+}

examples/CustomPortalContent/CustomPortalContent.ino

@@ -2,12 +2,13 @@
 #include <WiFiManager.h>
 
 WiFiManager portal;
+// WiFiManager reads this object while the portal is open, so it must outlive setup().
 WiFiManagerParameter brokerHost("broker_host", "MQTT broker", "mqtt.local", 40);
 
 void setup() {
     Serial.begin(115200);
 
-    portal.portalAddParameter(&brokerHost);
+    portal.portalAddParameter(&brokerHost);  // Adds an application-owned setting to the built-in form.
 
     // WiFiManager copies this read-only status section when it is registered.
     PortalInfoSection deviceInfo;
@@ -28,7 +29,7 @@ void setup() {
     portal.portalAddHomeCard(hint);
 
     portal.setSaveParamsCallback([](WiFiManager::WiFiManagerRequestArgs) {
-        // A product validates and persists this value here; this demo only prints it.
+        // Validate and persist a copy in the application; this example only reports it.
         Serial.print("MQTT broker selected: ");
         Serial.println(brokerHost.getValue());
     });
@@ -37,4 +38,6 @@ void setup() {
     portal.autoConnect("WiFiManager Content", "example-pass");
 }
 
-void loop() { portal.process(); }
+void loop() {
+    portal.process();  // Serves portal requests until provisioning completes or times out.
+}

examples/StationProfiles/StationProfiles.ino

@@ -10,10 +10,12 @@ struct StoredProfiles {
     WiFiManagerStationProfiles profiles;
 };
 
+// The application owns persistence; WiFiManager only chooses and verifies profiles.
 class EepromProfileStore final : public WiFiManagerStationProfileStore {
 public:
     bool begin() {
 #if defined(ESP32)
+        // ESP32 EEPROM emulation can fail to reserve its backing region.
         return EEPROM.begin(sizeof(StoredProfiles));
 #else
         EEPROM.begin(sizeof(StoredProfiles));
@@ -25,6 +27,7 @@ public:
         StoredProfiles stored{};
         EEPROM.get(0, stored);
         if (stored.magic != kStoreMagic) {
+            // Treat erased or unrelated EEPROM as having no profiles.
             return false;
         }
         profiles = stored.profiles;
@@ -32,6 +35,7 @@ public:
     }
 
     bool save(const WiFiManagerStationProfiles& profiles) override {
+        // WiFiManager calls this only after it has verified the submitted candidate.
         EEPROM.put(0, StoredProfiles{kStoreMagic, profiles});
         return EEPROM.commit();
     }
@@ -53,11 +57,12 @@ void setup() {
         return;
     }
 
+    // Both objects are global because station retries continue after setup() returns.
     portal.setStationProfileStore(&profileStore);
     portal.setStationRecoveryInterval(30000);
     portal.startStationConnection("WiFiManager Profiles", "example-pass");
 }
 
 void loop() {
-    portal.process();
+    portal.process();  // Advances connection attempts and serves provisioning when needed.
 }