mostly doc changes per review feedback.

There were also a couple of minor code changes (variable renames and such)
but no algorithmic changes.