it's been a few years since i used arduino, and i had to brush on a few basics to find my feet again.
i think it would be fantastic if you folks could habitually include some more examples in your reference material, eg. pinmode.... could have an example declaring digital and analog pins as outputs, so i don't have to keep searching to discern that while analog pins are referenced as A#, digital pins are not D# but just #.
i don't think it would kill anyone if you included examples for "all four cases". sometimes people like to do things while their thoughts are belaboured with other issues in life. making things simple and tangible helps.
simple examples like this would facilitate the rate of progress for the aspiring nescient.
while referencing MIDIUSB i was only lucky in searching to discern that the bytes are internally declared so i wouldn't have to write my own decomposition. if i hadn't been doing this for decades, i could only imagine the amount of frustration someone would have to go through until they can turn this simple library into an functioning routine. then people would write more stuff themselves instead of all the borrowing one sees instead of individual work.
Except, of course, for some boards such as the ESP8266 where pins are referred to with a D prefix unless you want to refer to the actual pin on the chip, in which case you leave off the D prefix. To complicate things further there is not a 1:1 relationship between the D pin numbers and the chip pin numbers
It is, however, generally safe to use the pin number as printed on the board
Don't jump to the conclusion that everybody actually reads the reference pages and if they do that they take any notice of them and don't forget that IDE contains examples of many of the Arduino functions
I agree that this is a very important concept to document clearly, but I don't think the pinMode() reference is the appropriate place for it. Instead, I would put in on that digital pins tutorial which is so prominently linked to from the pinMode() reference page. The pinMode() reference page should be for documenting pinMode(), and only for documenting pinMode().
Unfortunately, although the Arduino Language Reference content is accessible for anyone to make proposals (though whether the powers that be at Arduino will ever bother to consider that proposal is another question), the library reference and tutorials content is hidden away (top secret stuff right?) sheltered from any chance of contributions from the community.