clarification in some of the API descriptions