updates for API documentation

These are updates to the comments used by YARD to generate the [API documentation](http://docs.aws.amazon.com/amazonswf/latest/awsrbflowapi/index.html).  Some classes/methods have been made private where they are confusing. Others have expanded documentation (to make them less confusing, as well).