updated api w/ better doc explanation