minor cleanup

added some comments and reorganized a bit.
note that one of the tests fail -- test suite still broken