Use PHPDocumentor to define "magic" methods within the classes

Reference http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.method.pkg.html
Add PHPDocumentor comments to method signatures

Reference #2
rebase of features/phpdocumentor
Merge pull request #32 from zendesk/dpawluk/rebase_mikealmond

Dpawluk/rebase mikealmond