comment tweaks for `dox --api` generation
README: add API section

generated from `dox --api < lib/parser >> README.md`