Aesthetic code changes.

* Removed misleading comments.
* Alphabetized the macros
* Moved example code to the top of the file, after the copyright notice.
* Added optional documentation string entry to SHOULD-BE.
* Added required documentation string entry to CONTEXT.