Clean up comments in the code

[ceball]

Some comments are out of date (e.g. because of changes in recent Python versions, including improvements to documentation), some are confusing, some should be issues or wiki items, etc...