Fix and add details to Serial doc (#7521)

Fixes #7484

Clarify blocking case for write()

Add flush() method.

Missing ), clarifications

doc/reference.rst

@@ -151,12 +151,31 @@ milliseconds is not recommended.
 Serial
 ------
 
-``Serial`` object works much the same way as on a regular Arduino. Apart
-from hardware FIFO (128 bytes for TX and RX) ``Serial`` has
-additional 256-byte TX and RX buffers. Both transmit and receive is
-interrupt-driven. Write and read functions only block the sketch
-execution when the respective FIFO/buffers are full/empty. Note that
-the length of additional 256-bit buffer can be customized.
+The ``Serial`` object works much the same way as on a regular Arduino. Apart
+from the hardware FIFO (128 bytes for TX and RX), ``Serial`` has an 
+additional customizable 256-byte RX buffer. The size of this software buffer can
+be changed by the user. It is suggested to use a bigger size at higher receive speeds.
+
+The ``::setRxBufferSize(size_t size)`` method changes the RX buffer size as needed. This 
+should be called before ``::begin()``. The size argument should be at least large enough
+to hold all data received before reading.
+
+For transmit-only operation, the 256-byte RX buffer can be switched off to save RAM by 
+passing mode SERIAL_TX_ONLY to Serial.begin(). Other modes are SERIAL_RX_ONLY and 
+SERIAL_FULL (the default).
+
+Receive is interrupt-driven, but transmit polls and busy-waits. Blocking behavior is as follows:
+The ``::write()`` call does not block if the number of bytes fits in the current space available
+in the TX FIFO. The call blocks if the TX FIFO is full and waits until there is room before 
+writing more bytes into it, until all bytes are written. In other words, when the call returns, 
+all bytes have been written to the TX FIFO, but that doesn't mean that all bytes have been sent 
+out through the serial line yet.
+The ``::read()`` call doesn't block, not even if there are no bytes available for reading.
+The ``::readBytes()`` call blocks until the number of bytes read complies with the number of 
+bytes required by the argument passed in.
+The ``::flush()`` call blocks waiting for the TX FIFO to be empty before returning. It is 
+recommended to call this to make sure all bytes have been sent before doing configuration changes 
+on the serial port (e.g. changing baudrate) or doing a board reset.
 
 ``Serial`` uses UART0, which is mapped to pins GPIO1 (TX) and GPIO3
 (RX). Serial may be remapped to GPIO15 (TX) and GPIO13 (RX) by calling
@@ -180,14 +199,13 @@ instead, call ``Serial1.setDebugOutput(true)``.
 You also need to use ``Serial.setDebugOutput(true)`` to enable output
 from ``printf()`` function.
 
-The method ``Serial.setRxBufferSize(size_t size)`` allows to define the
-receiving buffer depth. The default value is 256.
-
 Both ``Serial`` and ``Serial1`` objects support 5, 6, 7, 8 data bits,
 odd (O), even (E), and no (N) parity, and 1 or 2 stop bits. To set the
 desired mode, call ``Serial.begin(baudrate, SERIAL_8N1)``,
 ``Serial.begin(baudrate, SERIAL_6E2)``, etc.
-
+Default configuration mode is SERIAL_8N1. Possibilities are SERIAL_[5678][NEO][12].
+Example: ``SERIAL_8N1`` means 8bits No parity 1 stop bit.
+ 
 A new method has been implemented on both ``Serial`` and ``Serial1`` to
 get current baud rate setting. To get the current baud rate, call
 ``Serial.baudRate()``, ``Serial1.baudRate()``. Return a ``int`` of
@@ -206,7 +224,7 @@ current speed. For example
 
 | ``Serial`` and ``Serial1`` objects are both instances of the
   ``HardwareSerial`` class.
-| I've done this also for official ESP8266 `Software
+| This is also done for official ESP8266 `Software
   Serial <libraries.rst#softwareserial>`__
   library, see this `pull
   request <https://github.com/plerup/espsoftwareserial/pull/22>`__.