Modified file doc header so that important info about usage and buffer
size show up on main API doc page instead of file doc page;
added comment in a couple of places to remind reader that buffer size
must be powewr of 2.