Clean up cshake() and resolve old issues

Clean up cshake() and resolve old issues

C++ conversion in Id190e36 exposed some "interesting" use of the
variable toler caused by an ancient bug that has since been resolved.
Investigation showed that variable never meant anything to do with a
tolerance!

Renamed a bunch of variables for clarity and consistency. Documented
the core function. Clarified code comments and manual sections
accordingly.

Added some unit tests while trying to understand what things were
actually going on.

Refs #1255

Change-Id: I5b5eee0b8f3f4761ce9cb681dbdb0d4526a6761d