update docs and comments