more cleanup for #161, this includes some documentation