added documentation and changed some functions return types