code review and documentation tweaks