tweak docs, add inline docs for helper macro functions.