Question: The documentation on Arduino's website shows `SoftwareSerial::read()` as returning a `char`. ([link](https://www.arduino.cc/en/Reference/SoftwareSerialRead))

The header shows that the method returns an `int`. ([link](https://github.com/arduino/ArduinoCore-avr/blob/7a2e1cd815266fef3012a5c9b48f88d78551f838/libraries/SoftwareSerial/src/SoftwareSerial.h#L103))

The cpp definition shows `SoftwareSerial::read()` returning the value from a buffer array of `uint8_t` values. ([link](https://github.com/arduino/ArduinoCore-avr/blob/7a2e1cd815266fef3012a5c9b48f88d78551f838/libraries/SoftwareSerial/src/SoftwareSerial.cpp#L402-L404))

Given all of this:

1. Why would the interface return an `int` instead of a `uint8_t`?
2. Why do the Arduino docs show it as returning a `char`?
3. Is it safe to send/receive 8-bits at a time using this library?

For (3) I'm using an HC-06 if that matters.

Answer: 
1. You'll see in the code just above your third link that the function can return a value of `-1` if there is no data present. Thus a 16-bit value is used to cover the range of 8-bit `uint8_t`s, plus one extra value to show 'no valid data available'.
2. For simplicity, I guess.
3. Yes. This is what it's designed for.

In short, for all intents and purposes, only an 8-bit value is returned, but if you were to read into an `int`, you couldn't differentiate between a valid and invalid value.
> 
> The documentation on Arduino's website shows SoftwareSerial::read() as returning a char.
> 
> 
> 

No it doesn't. There is nothing in the documentation that tells you the return type. There is only an example where the returned value is assigned to a `char` variable. That doesn't mean that it returns a char - it just means that whatever data type it does return can be invisibly cast to a `char` by the compiler.

> 
> The header shows that the method returns an int.
> 
> 
> 

Indeed it does. That is because that is what it returns.

> 
> The cpp definition shows SoftwareSerial::read() returning the value from a buffer array of uint8\_t values.
> 
> 
> 

Yes, because the valid data that it deals with is 8 bits in size. Just because it handles 8 bit "valid" data doesn't mean that that's *all* it ever wants to return. The "no data available" return value of -1 is obviously not something that is stored in the data. It's a status, not data. 

---

> 
> Why would the interface return an int instead of a uint8\_t?
> 
> 
> 

Because a `uint8_t` cannot encompass all the functionality stated in the "Returns" section:

> 
> the character read, or -1 if none is available
> 
> 
> 

You can't return -1 in a `uint8_t`.

> 
> Why do the Arduino docs show it as returning a char?
> 
> 
> 

It doesn't - as I mentioned above. It makes no claims at all about the returned data type.

> 
> Is it safe to send/receive 8-bits at a time using this library?
> 
> 
> 

Yes. It performs serial data transfers using 8-N-1 by default. That's 8 data bits, no parity, and one stop bit. 

---

It's this kind of confusion with return types and bytes and integers and things that make people ask why they keep getting ÿÿÿÿÿÿ on the serial monitor. That's -1 cast as a char. I.e., "no data available" but they ignore that and treat everything returned as a `char` - most probably because the Arduino documentation shows an overly simplified example that ignores the possibility of a -1 being returned and treats everything as a `char`.

IMHO much of the Arduino documentation is somewhat sub-par and should not be taken literally - only as a rough guide for what is available. The same goes for much of their example code and projects.