update docs from review: clarity and removing comments