some docs update and a helper function