more design doc updates, also some minor code comment changes