Confusing documentation for Leonardo serial

[GoogleCodeExporter]

What change would like to see?

The documentation for Serial under the Leonardo suggests using:

// while the serial stream is not open, do nothing:
while (!Serial) ;

It isn't made clear that this should be *after* doing Serial.begin(). 
Intuitively, you would expect to do it before, as it would seem that doing a 
"begin" on something that is false or 0 would not work.

However I see from the code that the Serial_ class (and also HardwareSerial) 
provides an operator bool() which supports this behaviour.

I suggest that the documentation be amended to provide a clearer example, eg.

Serial.begin (115200);
// now wait for the serial stream to be ready ...
while (!Serial) ;

Also, quite a few of the example Communication sketches (eg. Dimmer, MIDI, 
Graph) do not incorporate this line at all.

Why?

It's all very well saying to wait for something to become true, but it is 
important to say *when* this should be done.

Would this cause any incompatibilities with previous versions?  If so, how
can these be mitigated?

No, this is documentation.

Reference: http://arduino.cc/en/Guide/ArduinoLeonardo

Original issue reported on code.google.com by n...@gammon.com.au on 10 Jul 2012 at 11:47

[GoogleCodeExporter]

Passing this one to Tom.

Original comment by dmel...@gmail.com on 10 Jul 2012 at 12:24

• Added labels: Component-Examples

[GoogleCodeExporter]

Original comment by s.fitzge...@arduino.cc on 2 Apr 2013 at 12:34

• Changed state: Started

[GoogleCodeExporter]

Original comment by s.fitzge...@arduino.cc on 4 Nov 2013 at 7:23

• Changed state: Done