Library reference pages may list incompatible boards in the compatibility list

[sterretjeToo]

https://www.arduino.cc/reference/en/libraries/keyboard/

Arduino Uno/Mega/Nano are included in the compatibility list even though they are not compatible with the Keyboard library.

Additional context

Additional reports

• Arduino IoT Cloud Docs arduino-libraries/ArduinoIoTCloud#380 (comment)
• https://forum.arduino.cc/t/arduino-keyboard-not-working-on-arduino-uno-r3/1102400
• https://forum.arduino.cc/t/documentation-for-keyboard-library-needs-some-correction/1126221
• https://forum.arduino.cc/t/sketch-funktioniert-nicht-keyboard/1099364/6
• https://forum.arduino.cc/t/issue-on-keyboard-library/1065385
• https://forum.arduino.cc/t/what-is-wrong-here/1080550/7
• https://forum.arduino.cc/t/why-is-arduino-nano-usable-as-usb-keyboard-controller/1333682

Related

• Library reference manual Compatibility page is incorrect arduino-libraries/Mouse#46

[matthijskooijman]

I suspect this list is autogenerated from the "architecture = avr" or so in the library.properties. I don't think libraries can explicitly state compatibility with some boars, but not others, so this should probably be fixed in the description instead (and looking at that page, the "compatibility note" even already does that, though it might be a bit more specific maybe).

[per1234]

Hi @sterretjeToo.

@matthijskooijman already answered while I was writing, but I'll post anyway in case there is a little bit of additional information:

The library reference pages like https://www.arduino.cc/reference/en/libraries/keyboard/ are automatically generated for all the libraries in the Arduino Library Manager based on the information in their library.properties metadata file.

The "Compatibility" list on the reference pages is based on the architectures field of that file. The reference page generator simply adds all the official boards of each architecture in the field to the list.

As in this case, a library might require capabilities that are not provided by all boards of that architecture. There is no machine readable data that would allow the generator to understand this so boards that are incompatible with the library may be listed in the reference page.

There has been some internal discussion about how the library metadata system might be expanded to indicate board compatibility, but for now we settled on warning the reader about the situation via the "Compatibility note" on the reference page:

Compatibility Note

Note: while the library is supposed to compile correctly on these architectures, it might require specific hardware features that may be available only on some boards.

[sterretjeToo]

Unfortunately that note does not reveal anything to the beginner that consults the page. Please explain how somebody is to know what that specific hardware is?

[per1234]

the "Compatibility note" on the reference page:

Compatibility Note

Note: while the library is supposed to compile correctly on these architectures, it might require specific hardware features that may be available only on some boards.

The note has since been changed to one that is even more vague and cryptic, as well as being easier to overlook. It now says:

Compatibility with an architecture means that code can be compiled and uploaded to a board from the list below:

The note is inaccurate since the list can contain boards for which the library will not compile. For example, it claims that the Keyboard library can be compiled for the UNO R3, classic Nano, and Mega boards:

https://docs.arduino.cc/libraries/keyboard/

[per1234]

The reference page content is also potentially problematic in the case of libraries that use the * wildcard value, and a different manner than the others mentioned here since no caveat at all is displayed in this case. It only says:

This library is compatible with all architectures so you should be able to use it on all the Arduino boards.

For example (though admittedly not the best one since there is a good chance this high level library actually is compatible with all board):

https://docs.arduino.cc/libraries/stepper/#Compatibility