One of the things that I find hard to understand is how the various MICROPY_ macros can be used to adjust the capabilities included in the firmware for a particular board or build. More so as I have not been able to find documentation, other than the occasional comment in source.
There is a rather strict naming convention, that does give some context, but also assumes a familiarity with the code base.
In total there are nearly 1_800 unique MICROPY_macros defined and used in the code base and for only 282 of them there is a comment line preceding ( comment number may be off , based on a rather simplistic regex scan)

As there are a lot of macros that may benefit from some level of documentation.
what I normally do is to search for occurrences, scan for comments and try to read the code to glean the intent from that.
This is something where LLM models scale better than humans.

I have built a simple tool to

• scan the codebase for the macro definitions, comment , and usage
• store that in a sqlite database
• for each unique macro
  • collect the surrounding lined for the occurrences
  • run them through a LLM (4o-mini) with the ask to generate a one-line description ( costs , approx 12 cents for this set)
  • save that description back into the db
• generate some markdown tables from that ( grouped by the 2nd word in the macro name)

the result looks promising :https://gist.github.com/Josverl/9def801af4a80a79de9ae19876efb22f#file-micropy_macros-md
Andmay will need some manual cleanup

now my questions are :

• is this useful enough for should something like this be part of the documentation
• if so how / where ( .MD , .RST , single page , multi page etc)
• what should be improved / changed / omitted
• how to maintain such documentation as new PRs add relevant macros over time