PEAR/FunctionComment: bug fix - handling of blank lines in pre-amble

[jrfnl]

Description

The PEAR.Commenting.FunctionComment sniff intends to flag blank lines between a function docblock and the function declaration.

However, as things are, there are - IMO - two bugs in the logic for this:

Given a code block which looks like this:

class HandleBlankLinesBetweenDocblockAndDeclarationWithAttributes
{
    /**
     * Blank line between docblock and attribute.
     *
     * @return mixed
     */

    #[ReturnTypeWillChange]

    #[

        AnotherAttribute

    ]#[AndAThirdAsWell]

    public function blankLineDetectionA()
    {

    }//end blankLineDetectionA()
}

There will be only one error and it will read:

[x] There must be no blank lines after the function comment (PEAR.Commenting.FunctionComment.SpacingAfter)

This is confusing as the blank line may not be after the function comment, but after an attribute instead.

Additionally, the sniff also flags blank lines within attributes, while that is outside of the purview of the sniff. (Should be handled by an attribute specific sniff)

What I would expect would be for the sniff to:
a) Throw a separate error for each (set of) blank lines found.
b) For the error message to more accurately reflect what is being flagged.

Note: while in PHPCS this gets confusing, the fixer already fixes this correctly.

This commit changes the SpacingAfter error to comply with the above expectations

Includes test, though there are also some pre-existing tests which show this issue and for which the behaviour is changed.

Note: while it will still be messy, it may be easier to review this PR while ignoring whitespace changes.

Suggested changelog entry

PEAR.Commenting.FunctionComment: improved message for "blank lines between docblock and declaration" check.
PEAR.Commenting.FunctionComment will no longer remove blank lines within attributes.

Related issues/external references

Loosely related to #152

Types of changes

• Bug fix (non-breaking change which fixes an issue)