macros: add phpdoc and tweak README