updates, mostly documentation, in response to code review