Serial.begin() - enhance documentation and add example for changing the baud rate

[roboter-basteln]

The documentation of Serial.begin() does not limit the use to one time - which is correct. However, it's not described how to use Serial.begin() multiple times.

I have asked a Stack Exchange question about it. From the answer I got there, I would like the documentation to be enhanced like this:

Description
[...]
`Serial.begin()` can be used multiple times within a program. 
Be aware that data that was already written might still be buffered. 
Therefore, you might want to use `Serial.flush()` before changing the baud rate.

and add an example

Example Code
[...]
Changing the baud rate:
void loop() {
      Serial.begin(1200);
      Serial.println("Hello");
      Serial.flush();
      Serial.begin(9600);
      Serial.println("world");
      Serial.flush();
 }

This could be useful e.g. if the two communication ends want to negotiate the baud rate. Forgetting to flush will likely cause effects that prevent successful negotiation.

[per1234]

My feeling is that this is a very corner case and that, considering that we do already describe the asynchronous nature of serial output, it should be fairly obvious already to someone implementing something as advanced as a negotiated baud rate change. For this reason, I don't think it's worth making the documentation less friendly to the beginners who don't need this information by adding it.

[roboter-basteln]

Well then... if you think Arduino is for beginners, then good luck. C and C++ are not for beginners.
And just to mention: that non working code was written by a 9 year old kid - and I (age of 43) could not help him, because the documentation was so poor.

Luckily, the license allows me to create my own copy of the Arduino documentation.