add docs and example, + tweak API