clean up the comments

many changes.  some behavioral.  comments bent to reflect current state.