doc changes, and tidying up some of the code