some additional error checks and better source documentation