misc api doc edits - typos and sentence flow, nothing conceptual

/cc @eastridge