Add PhpDoc-comments to code examples in the documentation

[localheinz]

Currently, in the code examples in the documentation, PhpDoc-comments for class methods are missing. While I believe adding them doesn't do any harm, I'm convinced that these would greatly improve the documentation, as well as convey good craftsmanship.

[localheinz]

Also, most of the detailed explanations of code snippets could be gotten rid of and instead, these explanations could be fit into comments within the code.

Have a look at this:

[GeeH]

Hi @localheinz, it's a very valid point, would be delighted to receive a PR with these modifications :)