Php-cs-fixer: (Priority?) issue with phpdoc_annotation_without_dot (and whitespace)

[dmvdbrugge]

This is either a priority issue, where no_trailing_whitespace_in_comment needs to run before phpdoc_annotation_without_dot, or the latter should take whitespace into account.

The PHP version you are using ($ php -v):

PHP 7.1.18 (cli) (built: May 25 2018 19:18:59) ( NTS )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.1.0, Copyright (c) 1998-2018 Zend Technologies
    with Zend OPcache v7.1.18, Copyright (c) 1999-2018, by Zend Technologies

PHP CS Fixer version you are using ($ php-cs-fixer -V):

PHP CS Fixer 2.12.1 Long Journey by Fabien Potencier and Dariusz Ruminski

The command you use to run PHP CS Fixer:

vendor/bin/php-cs-fixer fix -v --using-cache=no

The configuration file you are using, if any:

Basically the same as dmvdbrugge/dynamic-components, except explicit_string_variable, header_comment, no_alternative_syntax, and no_unset_on_property

If applicable, please provide minimum samples of PHP code (as plain text, not screenshots):

• before running PHP CS Fixer (no changes):

<?php

/**
 * @throws \Exception If something goes wrong.     
 */
function throwMe()
{
}

• after first run:

--- Original
+++ New
@@ @@
 /**
- * @throws \Exception If something goes wrong.     
+ * @throws \Exception If something goes wrong.
  */
 function throwMe()

• after second run:

--- Original
+++ New
@@ @@
 /**
- * @throws \Exception If something goes wrong.
+ * @throws \Exception if something goes wrong
  */
 function throwMe()

• expected:
  Immediately arrive at the last step

Meta: this is case 13 of #3844

[SpacePossum]

I would prefer the phpdoc_annotation_without_dot rule to be changed such that it will strip trailing space (but not line breaks) following a dot it want to fix. I think there is no good reason to keep the space after the dot.

[dmvdbrugge]

following a dot it want to fix

At the moment, the fixer doesn't even find that dot because it just looks at the last character of the line. It should account for possible whitespace at the end as well, but the removal of the whitespace is imho the responsibility of no_trailing_whitespace_in_comment. (Talking about single responsibility 😉) Of course also depends on how easy it is to do one vs the other.

As long as phpdoc_annotation_without_dot accounts for possible whitespace, at least there is no prio issue anymore. But I'll leave the decision to you guys.

[SpacePossum]

TBH I rarely use the rule because it doesn't always make sense. PSR5 makes the assumption that all PHPDocs are written in left-to-right languages.
That aside; I wonder how someone reasons that a sentence should not end with a dot but ending with spaces, tabs or non-printable chars. is fine.

Patching the no_trailing_whitespace_in_comment fixer would be the easiest to resolve this issue.

[dmvdbrugge]

I have a different case:

/**
 * This is a broken phpdoc
 *
 * @param string $str The next line has no *.

 * @return int The number of runs needed to fix this is 2 :( .
 */
function fixMe($str);

The first run, align_multiline_comment fixes the missing *. Only the second run, phpdoc_annotation_without_dot kicks in.

@kubawerlos is this perhaps fixed in your PR as well, or do we need another issue for this?

[SpacePossum]

this is a true priority issue between the fixers, phpdoc_annotation_without_dot should not add a new line with * IMHO

[dmvdbrugge]

I get that the dot-fixer should not add the *, but the problem is the fixer only kicks in after the * is there. Is it because it's not considered a "valid docblock"? Because then _every_ phpdoc fixer must run after align_multiline_comment

[SpacePossum]

if the align_multiline_comment add the [indent]* to the PHPDoc to complete it, than it should be run before every other PHPDoc fixer I think

[dmvdbrugge]

Yes that's what I said 😉 I shall create a new priority issue.

[SpacePossum]

I think this issue itself is fixed in https://github.com/FriendsOfPHP/PHP-CS-Fixer/pull/3867 . The other one has its own issue.