include: devicetree: gpio: add doxygen to all GPIO headers header files

[kartben]

Document Arduino MKR, ST Morpho etc. so as to have them conveniently visible in the API reference

https://builds.zephyrproject.io/zephyr/pr/95349/docs/doxygen/html/group__devicetree-gpio-pin-headers.html

This builds on top of #95320 as I basically realized it would be nice to have all GPIO nexuses showing up in the docs. I will rebase once the other PR is merged but would appreciate feedback on everything but the first 3 commits in this PR.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[pillo79]

LGTM and thanks! Since we're making this more visible, I would take the opportunity to add a note to the Uno R3 layout that mentions something along those lines:

Usually Arduino pins are numbered starting from the digital pins, and the analog pins follow. Note the sequence here instead starts from the analog pins, so D0 == 6.

(unfortunate choice when it was added; not sure we can switch now without breaking compatibility).

[kartben]

LGTM and thanks! Since we're making this more visible, I would take the opportunity to add a note to the Uno R3 layout that mentions something along those lines:

Usually Arduino pins are numbered starting from the digital pins, and the analog pins follow. Note the sequence here instead starts from the analog pins, so D0 == 6.

(unfortunate choice when it was added; not sure we can switch now without breaking compatibility).

I think I might be missing your point. Isn't the whole point of now having macros that folks won't really have to worry about the underlying actual value, and hence why we clearly encourage folks to use the constants? https://github.com/zephyrproject-rtos/zephyr/blob/main/dts/bindings/gpio/arduino-header-r3.yaml#L47-L48

[pillo79]

LGTM and thanks! Since we're making this more visible, I would take the opportunity to add a note to the Uno R3 layout that mentions something along those lines:

Usually Arduino pins are numbered starting from the digital pins, and the analog pins follow. Note the sequence here instead starts from the analog pins, so D0 == 6.

(unfortunate choice when it was added; not sure we can switch now without breaking compatibility).

I think I might be missing your point. Isn't the whole point of now having macros that folks won't really have to worry about the underlying actual value, and hence why we clearly encourage folks to use the constants? https://github.com/zephyrproject-rtos/zephyr/blob/main/dts/bindings/gpio/arduino-header-r3.yaml#L47-L48

Sure, but Arduino users have been trained to numbers unfortunately, so it is extremely tempting for people interested in the Arduino connectors to try using them anyway. I was pointing out that while other connectors happen to match with our standard numbering, arduino-header-r3 does not. (And that choice was made 5 years before the macros, so downstream will break if we change it. 🙁)