api: more docstrings and some fixes