add README
revise proposed API
Merge pull request #1 from Trott/README

add README