docs: more thoughtful API docs