ADD MORE EXPLANATORY COMMENTS

[svhawkins]

Add more structured comments, especially for functions and structs

• add commments in the main programs
• add comments describing tests and what they are testing more in detail (ie write out the 'code snippet' version of the ASTs)
• add comments for enumerations

for functions and/or member functions:

/**
*@name
*@brief  <brief description of function>
*@param <parameter name> <description, include type>
*@param <parameter name> <description, include type>
*...
*@return <descritption, include type>
*
* <optional> detailed description
* - highlight failure cases
* - highlight special cases
* - highlight behavior/state changes
*/

for structures/classes:

/*
* structure name
* @brief <description>
* @member <type : member variable name> <description>
*/