#651: fix bug and update documentation

This adds documentation about the extra functionality introduced for #651 in #850.

It also fixes a bug in a variable name.

@arjclark, please review.