[Proposal] Remove unstable Annotation sniffs and replace with OOB ones

[lenaorobei]

Reason

Rules under Magento/Annotation folder rely on token index instead of token content and do not verify findings (findPrevious and findNext can return false). This leads to false-positive findings and and errors during execution (#38).

Solution

1. Remove unstable Magento/Annotation sniffs.
2. Add out-of-box PHP CodeSniffer rules that cover the bigger part of functionality + add extra useful and efficient checks.

    <!--Ensures doc blocks follow basic formatting.-->
    <rule ref="Generic.Commenting.DocComment">
        <severity>5</severity>
        <type>warning</type>
    </rule>
    
    <!--Parses and verifies the class doc comment.
        Verifies that:
      - A class DocBlock comment exists.
      - The comment uses the correct DocBlock style.
      - There are no blank lines after the class comment.
      - No tags are used in the DocBlock.-->
    <rule ref="Squiz.Commenting.ClassComment">
        <severity>5</severity>
        <type>warning</type>
    </rule>
    
    <!--Allow tags in the aforesaid sniff.-->
    <rule ref="Squiz.Commenting.ClassComment.TagNotAllowed">
        <severity>0</severity>
        <type>warning</type>
    </rule>

    <!--Parses and verifies the doc comments for functions.-->
    <rule ref="Squiz.Commenting.FunctionComment">
        <severity>5</severity>
        <type>warning</type>
    </rule>

    <!--Verifies that a @throws tag exists for each exception type a function throws.-->
    <rule ref="Squiz.Commenting.FunctionCommentThrowTag">
        <severity>5</severity>
        <type>warning</type>
    </rule>

    <!--Parses and verifies the variable doc comment.-->
    <rule ref="Squiz.Commenting.VariableComment">
        <severity>5</severity>
        <type>warning</type>
    </rule>

3. Implement sniffs for missing rule: @inheritdoc formatting - issue [New Rule] Implement sniff for functions PHPDoc formatting #54

Bonus

Some of the OOB sniffs detect fixable issues that can be automatically fixed by phpcbf tool.

[lenaorobei]

@orlangur I believe you have some thought to say here 🙂

[paliarush]

Let's do the following:

1. Leave annotation sniffs in the Magento repository only. Remove all other sniffs from the Magento repository.
2. Ruleset in Magento repository should reference the new unified ruleset. Additionally it should still enable existing annotations sniff and disable standard annotation sniffs defined in the unified ruleset.
3. After initial release, non-standard annotation checks should stay in custom sniff and it should be moved to the new unified repository and included into unified ruleset. As a result there will be no custom rules defined in the Magento repository and all custom ones will be defined in the unified repository.