tweaks to API docs as per discussion