Header/documentation cleanup.

Reorder file to group common functionality together, and put more
common / basic stuff at the top.

Improve comments in general.

Author: zpostfacto