DOC: updated documentation to reflect latest changes in the API