updated docs to more represent desired api