comments on Arduino flush() method (esp8266#8318)

Author: d-a-v

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);

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))

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);

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;