improved helper functions and in-code doc