update doc strings for correctness, clarity
updates for aesthetics