Ok - I just went to the Serial.read() function definition on the Arduino site:
http://arduino.cc/en/Serial/Read
I just noticed that it reads:
"Returns...the first byte of incoming serial data available (or -1 if no data is available) - int"
Why isn't the return value of this function a byte, instead of an int?
So - why does Serial.read() return an int,
It allows the status and value to be returned in a single function call. It allows a loop like this...
int ch;
ch = Serial.read();
while ( ch != -1 )
{
if ( (char) ch == 'x' )
{
}
ch = Serial.read();
}
Aren't integers on the Arduino defined as 2 bytes long?
Yes.
and why doesn't the documentation match up?
I can't help with that one.
Also, what is the return value type for Serial.available() - it isn't mentioned in the documentation, either?
uint8_t (aka byte).