Deprecate @link and add relations to @see

[mvriel]

This proposal intends to add a relation type, or role, to the @see tag while keeping the tag backwards compatible.

Syntax proposal:

@see [URI | "FQSEN"] [<:type:>] [<description>]

Example:

@see \My\Class::myMethod() :alias: Description why this is an alias.

The relation type is considered to be an optional addition and may be omitted.
I also propose to create a separate list, or recommendations, for type names; this will help standardize and provide default meaning (comparable to http://www.iana.org/assignments/link-relations/link-relations.xhtml for the rel attribute of a link)

[dongilbert]

I like this concept and would support it. Are there any constraints on what :type: may be? Should there be constraints or just leave that up to the one writing the doc?

[mvriel]

My suggestion would be to provide recommendations, as is done with the rel attribute for a link, and allow people to come up with their own. I would also suggest to maintain the recommendations outside of the standard in a living document so that those may change without affecting the actual PSR

[philsturgeon]

I'm all for this. Have something in the meta docs that explains some recommended types, but do not actually list anything (or reference them at all) in the main doc.

[mvriel]

I have altered the text to deprecate @link and describe @see in some more detail