Document interfaces that should be implemented by boards platforms

[matthijskooijman]

trafficstars

Describe the request

We need some more exhaustive documentation about the "interface" that a core or variant should expose.

In particular:

• All of the required keys in platform.txt, boards.txt and programmers.txt, and what they are used for, should be listed. These keys form the "external interface" of the core, which can be used by the IDE or arduino-builder. A core can also contain arbitrary other keys, which are used for variable substitutions internally, but cannot be relied on to exist is all cores. Currently, this distinction is blurry and ad-hoc.
• All of the macros, functions and variables that a variant of the Arduino core should expose should be documented. Some of these are mean to be used by the sketch directly (and should actually be documented as part of the normal Arduino reference), but some of them are only used internally by the Arduino core as part of another API. Currently, no definitive list of these exists, making variants (both third-party and Arduino ones) inconsistent or incomplete.

Both of these pieces of documentation should be updated when the requirements change in future IDE or core versions, with the changes mentioned explicitly and with the IDE or core version that introduced them.

Describe the current behavior

The **Arduino Platform Specification documents a good deal of the structure and has examples, but is not exhaustive or explicit.

Additional context

Related

• https://github.com/arduino/arduino-cli/issues/846
• https://github.com/arduino/arduino-cli/issues/988
• https://github.com/arduino/arduino-cli/issues/1007
• https://github.com/arduino/arduino-cli/issues/1030
• arduino/Arduino#3371
• arduino/Arduino#3681
• https://github.com/arduino/docs-content/issues/359

Additional requests

• https://github.com/arduino/arduino-cli/issues/2751
• https://forum.arduino.cc/t/how-does-ide2-compile-multiple-in-files/1325307/8

Issue checklist

• [X] I searched for previous requests in the issue tracker
• [X] I verified the feature was still missing when using the latest nightly build
• [X] My request contains all necessary details