Documentation on the "byte" data type is very confusing and unclear

Development Libraries
#1

I wanted to better understand the byte data type, but the documentation actually confused me more and offered very little useful information.

https://www.arduino.cc/en/Reference/Byte

byte
Description

A byte stores an 8-bit unsigned number, from 0 to 255.

Example

byte b = B10010; // "B" is the binary formatter (B10010 = 18 decimal)

Does the 8-bit unsigned number from 0-255 HAVE to be in binary? If so, let's make that clear. Why not have the description show a range in binary and then in parenthesis include the 0-255? For example:

A byte stores an 8-bit unsigned number in binary form, from 0 to 11111111 (0 to 255)

Perhaps it is redundant to say 8-bit and binary in the same sentence, but it is certainly more clear for those of us who are still learning.

If it does not have to be in binary, why only show an example in binary? (at this point I'm assuming it does) Also, WHY did you include the comment using a variable "b" and then describe the "B" in the value? I understand that b and B are different, but I'm not as unfamiliar with programming as some people. How about we change that to:

byte ExampleVariable = B10010; // "B" in front of the binary number is required and indicates that the following number is in binary and not decimal form. (10010 = 18 in decimal form)

"(B10010 = 18 decimal)" really confused me for a bit. I know binary is only composed of 1s and 0s, so to see a B in the explanation really threw me for a loop. I know that's why you explained the "B" as being the binary formatter, but it wasn't clear at first glance. I suppose I am mostly confused by this explanation. If the byte MUST be binary, why do we have to use "B"? This is why I thought it might not have to be in binary. Another couple examples would really help as well.

Anyway, I think my explanation is becoming unclear as well. Assuming this is correct, can we just change it to this:

Description

A byte stores an 8-bit unsigned number in binary form, from 0 to 11111111 (0 to 255)

Example

byte FirstExampleVariable = B10010; // "B" in front of the binary number is required and indicates that the following number is in binary and not decimal form. (10010 in binary = 18 in decimal form)
byte SecondExampleVariable = B0; // (0 in binary = 0 in decimal form)
byte LastExampleVariable = B11111111; // (11111111 in binary = 255 in decimal form)

After all, it is the learners, like myself, who read these things. The documentation should be extremely clear, provide plenty of examples, and at times be redundant. Again, I came here because I'm unsure of how a byte works. If I'm wrong on any of this, that's fine, please correct my mistakes, but also please make some improvements.

#2

psyberjock:
Does the 8-bit unsigned number from 0-255 HAVE to be in binary?

No, you can do:

byte b = 18;

I agree that is a terrible example to have. The whole point of Arduino is to make this stuff accessible to beginners with little previous experience. It's unlikely that someone reading the byte reference page is going to care about binary notation, that should be in a different reference page because it just makes something that should be simple confusing. The only time I would use binary notation would be if each bit of the byte was being used to describe a boolean state, for example if it was controlling whether a series of LEDs were on(1) or off(0). If I want to set the value of a variable to 18 then I'll write 18, I'm a human not a computer.

#3

HighByte and LowByte also confused me. Well, first what confused me is that the title of the page and the URL capitalize functions which start with a lower-case letter, as they should.

Furthermore an example would have really helped me. For instance:

int aValue = 7189;             // 7189 is 0001 1100 0001 0101 in binary format
Serial.write(highByte(aValue));  // transmits 0001 1100
Serial.write(lowByte(aValue));  //  transmits 0001 0101

Then there's also endianness. Arduino is little-endian but some components are big-endian (check the wifishield classes, for instance). Do lowByte and highByte take that into consideration or do you have to check BYTE_ORDER yourself?

#4