There were a number of functions assigning their return value to
`error` without much explanation.  I added in some rudimentary
error checking to help flesh out the example.

Also, I reformatted all of the comments down to 80 cols (and in
some cases, slightly updated the wording).