Switch all class documentation to use correctly formatted PHPDoc syntax.

[blister]

Our code was originally documented in the early years before PHPDoc existed or had wide adoption.

Now that it exists, we should follow those conventions. Both Painfree.php and all the core classes and scripts inside of /includes need to be updated to use PHPDoc syntax and conventions.

Don't go crazy with it though. Just description, @params, and @returns will be enough for most of our use cases.