Documentation for MICROPY_* macros

[Josverl]

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
And may 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

[ricksorensen]

I think this is useful and should be part of the build/modify documentation. The main documentation could have a summary of what these macros can be used for and include a reference link to this index.

The grouping of macros helps a lot.

Thanks

[Josverl]

If I may ask; Would you search for/expect to find them in the docs, or in the wiki?

[ricksorensen]

I would put the general information in the doc, with the details in the Wiki.

[andrewleech]

A few months ago I actually parsed the codebase for these and built a kconfig frontend to view/configure the build using them. I got quite an effective description for most of them, though I went through a few rounds of broad code exploration to try to get a more complete picture of what the configs did.

There were a few aspects of the build system I didn't get working back then but that was a couple of llm generations ago so it would probably be much easier to get cleaned up now!

[Josverl]

My first aim is to document, as there is a lot of whitespace. I can see the use of the same info for a Kconfig, but I think that hinges on the clarity and accuracy of the descriptions.
Having a 1000 switches without clear meaning does not help much.

It would be interesting to compare the descriptions of your efforts, against these to help validate the good ones , and identify which are incorrect or need to be improved.