new optimization for scan to be smarter about memory allocation .. plus a few notes in the documentation