Add a sniff to force types in comments to use use statements.

[herregroen]

Typehints in comments should, if they refer to a namespaced class, always use a use statement and use the short form in the comment.

The following docblock would break this rule:

/**
 * A function.
 * 
 * @param \Yoast\WP\SEO\Input $input The input.
 *
 * @returns \Yoast\WP\SEO\Output The output.
 */

And the following docblock would be a correct replacement:

use Yoast\WP\SEO\Input;
use Yoast\WP\SEO\Output;

/**
 * A function.
 * 
 * @param Input $input The input.
 *
 * @returns Output The output.
 */

Ideally an auto-fixer would insert new use statements in alphabetical order at the top of the file and fix the comments directly.

We are aware not all WordPress tools would be able to correctly parse this notation but believe that the better way forward here would be to support this notation. Especially given that in the wider PHP open source environment this is also the standard.

[jrfnl]

Ideally an auto-fixer would insert new use statements at the top of the file and fix the comments directly.

I propose to address this in YoastCS 3.0 - also see #208

If my proposal in #208 would be accepted, the following rule can be added to the ruleset to address this (and auto-fix issues):

    <rule ref="SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly">
        <properties>
            <property name="searchAnnotations" value="true"/>
        </properties>
    </rule>

Note: more configuration for this sniff will be needed depending on choices made for other things (like exception, global functions, constants), but that's outside the scope of this issue.

use statements in alphabetical order

This is a separate request as there currently is no rule about use statements needing to be in alphabetically order.

If a rule to that effect should be added, it needs its own issue.

@herregroen Didn't you also want to forbid use import statements for the same namespace ? If so, this would need its own issue as well to make sure we address this.