I agree documentation around these intricacies are not so good as compared to other sections.
These are the ones that I use
You may replace k8 with K9 to get version 9 documentation.
Regarding building macros, what I have observed and Kentico support might be able to attest this is that they follow the API that you normally use programatically.
It may not be true always, however more or less I have observed, that it follows the case.