Added commentary on logic, todo items and some new tests

Reformatting should ideally be in a separate commit, so that we don't miss logical changes in amongst the cruft.