fix API and to be cleaner and align docs and tests