clarify comments
add API spec to README