update docs and code comments