Document the layout parameter of Keyboard.begin()

[edgar-bonet]

Since release 1.0.3, the Keyboard library supports international keyboard layouts. The requested layout is chosen via an optional parameter passed to Keyboard.begin(). This pull request documents this new feature of the library.

Defining custom layouts

Users can define their own keyboard layouts, and give them to Keyboard.begin(). I am not sure about the best approach to document this feature though, and thus I would appreciate some feedback from the community.

The way to use an existing layout is very easy, and well suited to the target audience of beginners. Defining a custom layout, however, is more of a feature for advanced users, and it should be documented in a way that doesn't make the beginners feel overwhelmed.

My approach in this PR is to point the users to the header file KeyboardLayout.h, which has extensive comments documenting the procedure. The assumption is that if someone is willing to look at a source file, he is presumably advanced enough to successfully define his own layout. This may not be the best approach though. Maybe add an extra document here with the information that is currently in that header file? In that case, should that document feature a warning like “this is for advanced users”? Maybe document also the way to contribute the layout back to the community?

[per1234]

My approach in this PR is to point the users to the header file KeyboardLayout.h, which has extensive comments documenting the procedure.

I think that is the correct approach. The Arduino Language Reference is intended to provide documentation of the language for its users in a manner that is friendly to beginners. Documentation of library code modification is out of scope for the Arduino Language Reference.

[edgar-bonet]

Thanks @per1234 for you thoughtful review!

Documentation of library code modification is out of scope for the Arduino Language Reference.

Note that the user can define a custom layout within their sketch. I still consider this a feature for advanced users though.

[per1234]

Note that the user can define a custom layout within their sketch.

Ermmm... I guess I should have taken time to properly understand the feature before commenting on this.

I do still think that fully documenting this custom layout feature on the Keyboard.begin() reference page would add too much complex content.

My thought is that what is provided here is perfectly sufficient for a first take at documenting the API expansion. It would definitely be worth giving consideration to providing a tutorial about adding additional layouts in a more accessible location (compared to the library source) on arduino.cc, then updating the note in the Keyboard.begin() reference page with a link to that tutorial. Maybe @karlsoderby or @kengdahl will have some thoughts on the subject of that tutorial?

[per1234]

Thanks so much for your follow through in providing documentation of the valuable enhancement you contributed to the Keyboard library code @edgar-bonet!

[MalcolmBoura]

The documentation should always encourage good practice and it is good practice to document parameters and return types. However, since aimed at beginners, there are places where a parameter explanation of "Optional parameter. Advanced feature please see the header file for details" is acceptable.

uint8_t etc are preferable in a memory constrained environment because then you know what you are getting. int and such like are platform dependent which can make portability problematic. For example ARM uses a 32 bit int and so some code will misbehave if reused on Arduino, which uses 16 bits, unless modified. Checking code to find every potential problem is time consuming and error prone and requires non-trivial understanding of how the code works. In conclusion, Arduino should be using the stdint types by default. The only exception is perhaps char.