To bad that perlapi is not complete, but I guess I get the level of documentation that I pay for. :-)
The perlapi POD file is autogenerated from the source code, and there are lots of holes in the coverage. I'm not suprised that the macros are the least documented portion of the code.
If you want better docs, get the fabulous "Extending and Embedding Perl" by Tim Jenness and Simon Cozens, for lots about XS in general and the Perl internals in specific.
HTH
John
