Audit and fix up the API documentation.

- Expand the API documentation and add more epydoc annotations
- Fix some stuff that somehow got out of sync with the code it describes
- Remove the "support both python2 and python binary names" hack at the
  top of the file. (It's too clever for its own good)