added documentation to all functions
improved return value handling