Fix annotation groups usage

[lcobucci]

The main issue here is that both PHPDocumentor and PHPUnit relies on @uses annotation - with different meaning.

I personally wouldn't use @uses the way PHPDocumentor defines but I wanted to first have the build fixed before suggesting changes.

BTW this would be my suggestion for annotation groups:

https://github.com/lcobucci/coding-standard/blob/940d248df0a3ff0d3ccfa3ea44c8566313863ce2/src/Lcobucci/ruleset.xml#L33-L52

[Ocramius]

@lcobucci I don't understand the diff: you just moved @uses up?

[lcobucci]

@Ocramius yeap... the input has @uses in the incorrect place (according to our config). This PR fixes it, thus making the build pass again.

As I tried to explain, our configuration groups @uses with @see and @link (which is the meaning that PHP Documentor gives for that annotation):

<rule ref="SlevomatCodingStandard.Commenting.DocCommentSpacing">
    <properties>
        <property name="linesCountBeforeFirstContent" value="0"/>
        <property name="linesCountAfterLastContent" value="0"/>
        <property name="linesCountBetweenDescriptionAndAnnotations" value="1"/>
        <property name="linesCountBetweenAnnotationsGroups" value="1"/>
        <property name="annotationsGroups" type="array">
            <element value="@internal, @deprecated,"/>
            <element value="@link, @see, @uses,"/>
            <element value="@ORM\, @ODM\,"/>
            <element value="@param"/>
            <element value="@return"/>
            <element value="@throws"/>
        </property>
    </properties>
</rule>

And our files were using PHPUnit's meaning of @uses (explicit coverage tracking).

I thought that we shouldn't discuss modifying the meaning of that annotation for our CS without having the build stable first.

[alcaeus]

Isn't there a @covers annotation for PHPUnit? What's the difference between that and @uses? If we can avoid the double meaning, I'm all for doing so.

[Ocramius]

@covers indicates coverage, and allows setting up the test suite in such a way that any coverage outside @covers leads to a Risky test, and therefore to a non-zero exit code.

@uses is used to indicate code that is used in a certain test, but is more like "other, unrelated units".

The typical example is a test like following:

/**
 * @covers \My\Authentication
 * @uses \My\UserId
 */
final class TestAuthentication extends TestCase
{
    // ...
}

[lcobucci]

@Ocramius I know, I think I've failed to explain again. Our groups were set based on this: https://docs.phpdoc.org/references/phpdoc/tags/uses.html and not on PHPUnit's meaning of @uses.

My intention with this PR was not to discuss whether this is right or wrong, our build is broken and this PR fixes it.

Please be explicit if you'd like to have the configuration changed, I can change the PR.

[Ocramius]

I don't mind either way. I don't think @uses is to be used like in PHPDocumentor, as it is exposing implementation details in the documentation of an API, so we should probably phase it out long-term (not sure how to do that properly in this repo)

[lcobucci]

Let's ask the person who configured the groups then... @Majkl578 what's your take here, mate?

[SenseException]

My intention with this PR was not to discuss whether this is right or wrong, our build is broken and this PR fixes it.

I think a fixed master build would be nice. It makes it easier for contributors to keep focus on their own tests. @lcobucci Are you going to add your group-suggestion in another PR or are you going to add it here after feedback?

[lcobucci]

@lcobucci Are you going to add your group-suggestion in another PR or are you going to add it here after feedback?

I can do either, my initial thought was to do the former.

[alcaeus]

🚢