updated docs with additional comments