improved error handling and documentation