phpDoc annotation spacing

[Majkl578]

Sniff to require a newline between between description and tags, a newline between annotation groups and no newline before/after phpDoc content.

Example:

    /**
     * Description
     * More Description
     *
     * @internal
     * @deprecated
     *
     * @link https://example.com
     * @see  other
     * @uses other
     *
     * @ORM\Id
     * @ORM\Column
     * @ODM\Id
     * @ODM\Column
     *
     * @param int[] $foo
     * @param int[] $bar
     *
     * @return int[]
     *
     * @throws FooException
     * @throws BarException
     */
    public function d(iterable $foo, iterable $bar) : iterable
    {
    }

This is based on spacing/format used in ORM, does this properly fit other projects (i.e. ODM) too?

Changes in ORM with this enabled are mostly (superfluous newlines) cosmetical: Majkl578/doctrine-orm@68920f1

[Majkl578]

Since this PR requires new property syntax for arrays, I put this conditional check in place. The ruleset is valid according to XML schema from 3.3.2-dev.

[morozov]

Right now, we allow PHP_CodeSniffer ^3.1.1. Given that the schema is invalid for versions <= 3.3.1, will PHP_CodeSniffer 3.1.1 be able to process those rules?

Judging by the milestone of squizlabs/PHP_CodeSniffer#2154, the new schema will be available in 3.4.0, not in 3.3.2.

Why don't we just wait for a new release and bump the requirement? Otherwise, we may run into a PHP 6 situation.

[Majkl578]

Yes it will, PHPCS itself doesn't validate the schema.
The referenced PR is not related to this part, we don't use the proposed extend here.

[Majkl578]

Addresses this problem: #84 (comment)

[morozov]

So what is the 3.3.2 change which the XML validation depends on?

[Majkl578]

squizlabs/PHP_CodeSniffer#2151

They forgot to update the schema to include the new <element> syntax for arrays (available since 3.3.0).

[morozov]

Gotcha. It'd be nice if they had validation internally as in PHPUnit (sebastianbergmann/phpunit#3048). Otherwise, the schema validity will have to be enforced by 3rd party's CI like ours.

[Majkl578]

Possibly something for PHPCS 4.0. :)

[malarzm]

From what I see in ODM we used to have no newline between @param and @return but I had to check 1.2 branch to find that, with 2.0 most param/return phpdocs got removed anyway :D

[deeky666]

I like this idea. Just for clarification: What exactly is a "annotation group"? Considering your example I would expect a newline between the @ORM and @ODM tags, no?

[Majkl578]

@deeky666 My assumption was that you either:

• don't mix those two on a single object as they're mutually exclusive (this is imho normal state in regular apps - an entity is either an ORM object or an ODM object),
• mix those in a generic package (i.e. some shared Entity) and then you may want both @O[RD]M\Id etc. together

But I may be wrong, I never worked with a hybrid application.

[deeky666]

@Majkl578 sure in this example it might not make much sense but if you have other annotation groups like from JMS/Serializer or whatever, I would not expect to mix those up with @ORM / @ODM

[Majkl578]

@deeky666 For annotations (or annotation namespaces) unspecied here, all unknown are put into a special group that is added at the end. Check the description here:

Annotations not in any group are placed to automatically created last group.

So for i.e. @JMS\Type, it'd end up just before */. These would be up to you to configure this per project, we can't provide defaults for all possible annotations/namespaces.

[Ocramius]

🚢