Add documentation and minor code-refactoring

How about adding something along the lines of `You may also want to convey this failure to your user.`.