From 9d024d17fd18dffa569fa646b5326b5e8f58b0d5 Mon Sep 17 00:00:00 2001
From: david gauchard <gauchard@laas.fr>
Date: Wed, 29 Sep 2021 15:22:30 +0200
Subject: [PATCH] comments on Arduino flush() method (#8318)

---
 cores/esp8266/HardwareSerial.h         | 2 +-
 cores/esp8266/Print.h                  | 5 ++++-
 libraries/ESP8266WiFi/src/WiFiClient.h | 2 +-
 libraries/ESP8266WiFi/src/WiFiUdp.h    | 2 +-
 4 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/cores/esp8266/HardwareSerial.h b/cores/esp8266/HardwareSerial.h
index ea17f60efa..3ef45892e6 100644
--- a/cores/esp8266/HardwareSerial.h
+++ b/cores/esp8266/HardwareSerial.h
@@ -183,7 +183,7 @@ class HardwareSerial: public Stream
     {
         return static_cast<int>(uart_tx_free(_uart));
     }
-    void flush(void) override;
+    void flush(void) override; // wait for all outgoing characters to be sent, output buffer is empty after this call
     size_t write(uint8_t c) override
     {
         return uart_write_char(_uart, c);
diff --git a/cores/esp8266/Print.h b/cores/esp8266/Print.h
index e5d8d1b1ef..67f3ba5502 100644
--- a/cores/esp8266/Print.h
+++ b/cores/esp8266/Print.h
@@ -110,7 +110,10 @@ class Print {
         size_t println(const Printable&);
         size_t println(void);
 
-        virtual void flush() { /* Empty implementation for backward compatibility */ }
+        // flush():
+        // Empty implementation by default in Print::
+        // should wait for all outgoing characters to be sent, output buffer is empty after this call
+        virtual void flush() { }
 
         // by default write timeout is possible (outgoing data from network,serial..)
         // (children can override to false (like String))
diff --git a/libraries/ESP8266WiFi/src/WiFiClient.h b/libraries/ESP8266WiFi/src/WiFiClient.h
index 6f89aede06..e7afcaa538 100644
--- a/libraries/ESP8266WiFi/src/WiFiClient.h
+++ b/libraries/ESP8266WiFi/src/WiFiClient.h
@@ -72,7 +72,7 @@ class WiFiClient : public Client, public SList<WiFiClient> {
   size_t peekBytes(char *buffer, size_t length) {
     return peekBytes((uint8_t *) buffer, length);
   }
-  virtual void flush() override { (void)flush(0); }
+  virtual void flush() override { (void)flush(0); } // wait for all outgoing characters to be sent, output buffer should be empty after this call
   virtual void stop() override { (void)stop(0); }
   bool flush(unsigned int maxWaitMs);
   bool stop(unsigned int maxWaitMs);
diff --git a/libraries/ESP8266WiFi/src/WiFiUdp.h b/libraries/ESP8266WiFi/src/WiFiUdp.h
index 9e72eb66ca..d8fbcbe221 100644
--- a/libraries/ESP8266WiFi/src/WiFiUdp.h
+++ b/libraries/ESP8266WiFi/src/WiFiUdp.h
@@ -92,7 +92,7 @@ class WiFiUDP : public UDP, public SList<WiFiUDP> {
   int read(char* buffer, size_t len) override { return read((unsigned char*)buffer, len); };
   // Return the next byte from the current packet without moving on to the next byte
   int peek() override;
-  void flush() override;	// Finish reading the current packet
+  void flush() override;	// wait for all outgoing characters to be sent, output buffer is empty after this call
 
   // Return the IP address of the host who sent the current incoming packet
   IPAddress remoteIP() override;