[DRAFT, WIP] PSR-5: PHPDoc Standard

This PR represents the current state of affairs with the PHPDoc Standard. Until this description and subject is altered this PR is considered a Work in Progress and not ready for a final review.

All feedback is welcome, please direct this to the PHP-FIG mailing list to prevent noise in this PR. This PSR covers so many subjects that unless the discussions are separated by topic that it will probably be quite impossible to follow in this PR.

I would also request that people open a thread per issue they would like to discuss and not combine several issues in a single mail; this will help to keep noise-levels down in discussions and for me to loook back or filter important information.

TODO items are tracked in the issue tracker for this PSR: https://github.com/phpDocumentor/fig-standards/issues
Ummm... Readability? Not really -- for humans, $ does not improve readability, it's confusing and not what you would actually see in the array. Maybe find a different way to word this.

And is the example below supposed to mean that $options looks like
array('required' => TRUE, 'label' => 'This is the label')

Maybe you should explicitly state this in the text to better show what the example means?

As a note, for readability, in the Drupal project our standard would be to document this like:

@param array $options
   An associative array with the following elements:
   - required: ...
   - label: ...

I personally think this is more human-readable than inline phpdoc (our docs parser makes bullet lists out of this). So I'd avoid saying the $ is "readable".