Many docblock fixes + move to phpDocumentor2 docs

In an effort to improve the presentation of the docs, I have written a script that will generate them using phpDocumentor2 — the script fixes up some minor issues in the output, and once it hits stable, should be possible to remove in favor of just using the actual phpdoc command.

This script is called like so;

`$ php generate-docs.php`

Additionally, to make sure the generated docs were good; I have made many changes to the existing docblocks to make them consistent with each other, valid, and made small edits such that they will produce nice documentation with phpDocumentor2.

I will follow this up with a PR on the gh-pages branch with the newly generated docs also. Note that updating the gh-pages branch is identical to before.