add documentation from hongkai code review
resolves final failing unit tests