DX: check fixer's options for wording

[kubawerlos]

Fixer align_multiline_comment currently has:

Configuration
-------------

``comment_type``
~~~~~~~~~~~~~~~~

Whether to fix PHPDoc comments only (``phpdocs_only``), any multi-line comment
whose lines all start with an asterisk (``phpdocs_like``) or any multi-line
comment (``all_multiline``).

Allowed values: ``'all_multiline'``, ``'phpdocs_like'`` and ``'phpdocs_only'``

Maybe better would be to update available option to all, phpdoc_like and phpdoc_only?

[coveralls]

coverage: 94.917%. remained the same
when pulling bf06339 on 6b7562617765726c6f73:dx_check_options_for_wording
into a5fa4c9 on PHP-CS-Fixer:master.

[keradus]

content of PR and text in PR opening are 2 separated things, do I understand right?

for changing options, why dropping plural?

[kubawerlos]

why dropping plural?

It's not dropping, it still checks for plural, only with and exception fo having phpdocs_* in backticks, as align_multiline_comment has.

[keradus]

Allowed values: 'all_multiline', 'phpdocs_like' and 'phpdocs_only'

Maybe better would be to update available option to all, phpdoc_like and phpdoc_only?

I read it as you want to change the plurality (while PR is doing something else)

---

after peer2peer discussion, comment in opening msg is standalone idea, not blocking content of the PR

[keradus]

I think right now we have only phpdocs_ (plural) as rule option, is it the case?

with that, maybe we should keep the opposite rule here, to have it plural for option?

or likely no - as we have only single rule having option like that, maybe we do not have enough options to decide if there should be a rule for it, sounds too early for me.

Original idea was to keep proper casing, which makes sense to have always the same casing for same, hm..., proper name. (polish "nazwa wlasna")

now , you suggest to unify using plural or singular, which really depends on the context and maybe should not be unified?

[kubawerlos]

I'd say they should be unified, but let's start with not allowing more plural usages.

[keradus]

only if whole option make sense when using singular form. not sure if that will be the case or not as we do not have many cases yet to validate that.

[keradus]

I dropped it on local machine to check how the error will look alike if someone would use phpdocs_ option in other fixer.

Outcome is confusing:

1) PhpCsFixer\Tests\Fixer\Phpdoc\AlignMultilineCommentFixerTest::testXxxFixerConfigurationDefinitions
[align_multiline_comment] `PHPDoc` must be in correct casing in option:comment_type.
Failed asserting that 1 is identical to 3.

[kubawerlos]

What is confusing in "PHPDoc must be in correct casing in option:comment_type."? It is quite clear to me what is wrong.

[keradus]

it was confusing as test was complaining about plural/singular and test failure description was complaining about casing.

not the case anymore with newest state of this PR