add clear error messages, fix comments