bunch of commenting and slight debug logging improvements