update API and docs

All functions now return iterators yielding dictionaries