minor performance-y changes
adding a bit of documentation