Update API docs

Yeah, this discussion belongs in a different location - let's avoid design decisions in API doc updates.  We update API doc after we decide changes to API