add some documentary comments and clean up a few details