more verbose loop documentation for future archiving