update docs and change function signature