api: added some comments and made some functions more efficient