some docs and little code review for recent work