add docs and improved error logging