completing the initial round of PHP documentation as per the WPCS

http://make.wordpress.org/core/handbook/inline-documentation-standards/php-documentation-standards/#1-functions-and-class-methods
updating 'last updated' dates