[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
As indicated in the example, you might want to say something about how if this is used inline, you should put it in {} to indicate where the description ends.

Also... Is the description supposed to be the link text? If so, please state this. If not, how is the description supposed to be displayed by documentation parser/displayer applications?

And can the description be multiple lines? Does that change if it is inside {}?

Regarding this being deprecated, can @see be used inline to make links? If not, then I think we still need @link.

For instance, in the Drupal API docs parser, @see lines are built into a "See Also" section on the documentation output, where @link is used to make inline links within paragraphs. We do not support markdown, so @link is the main way to make links.

So my preference would be to deprecate @link for stand-alone links, in favor of @see, but keep the in-line syntax.