Changing an existing API always creates pain.
But to create the same API function in two different modules that does 2 different things
in modules that are logically supposed to have the same API is, IMO, inexcusable.
So I'm not that picky on the names of functions, I am very picky that I believe that flush() should
do the same thing in HardwareSerial and SoftwareSerial.
(Maybe it's already been bugged)
The issue with this particular change/difference is that it silently breaks code with no warning.
Arduino 1.0 users can get burned when moving code between HardwareSerial and SoftwareSerial
because while the SoftwareSerial does not buffer TX characters and so a flush() call
will not affect TX output,
Code that uses flush() in an attempt to push out any buffered TX characters will break when used on SofwareSerial
as it will potentially throw away all the RX data rather than the intended function of ensuring that the TX buffer is pushed
out the port.
This is a SERIOUS problem.
On a side note:
I believe that what can add to the "flush" confusion is that different APIs
us the term "flush" differently.
termio which is now part of POSIX was used on tty serial ports even before C++ existed
"flush" means purge the data in the buffer (buffer can be rx or tx),
"drain" means push the data in the buffer out.
And it is similar in streamio which is used for sockets.
Win32 used similar meanings/definitions for "flush", and "drain" but also has a "purge" to purge buffers.
So from that "C" perspective, the old flush() functionality seemed more appropriate.
But it's only a name.
Since I'm an old C guy, from my vantage point it looks like the
the confusion comes from C++ stream/iostream picking "flush()" as the name of the function
to push out unbuffered data.
I wish that they had picked "drain()" instead as it would have been more consistent
with the existing C API terminology but it is way too late to ever change it.
So depending if you are a C person or a C++ person and which APIs you are more
accustomed to, "flush" has different meanings.
--- bill