Seeking clarification on use of capitalisation in @param descriptions in coding standard

[Synchro]

Q	A
Bug report?	no
Feature request?	no
BC Break report?	no
RFC?	no
Symfony version	n/a

The php-cs-fixer project has a fixer that enforces that descriptions in @param should not end with a . or a 。, which is fair enough (see #19198), however, while doing that, it also rigidly enforces that the description must not start with a capital letter, which seems entirely unrelated and illogical, and prone to introducing grammatical errors in many languages. Yet it claims that this is also official, definitive Symfony policy.

To be clear, it's enforcing that this:

 * @param string $a This is a string.

Must be reformatted to:

 * @param string $a this is a string

I did a survey of the Symfony codebase to find evidence for this policy, but found the opposite.
98% of the code base uses capitalisation of @param and @return tag descriptions, as do all the examples in the coding standard guide, where it's not mentioned as a policy either. It's also contrary to the examples used in PSR-5.

Can you please provide clarification on whether this is indeed Symfony coding policy?

[jvasseur]

I think the reason behind this rule is that the description must not be considered a sentence and so must neither be capitalized nor finish with a full stop.

But some words have to be capitalized even if there aren't at the start of a sentence so blindly lowercasing them may be to much.

[Synchro]

Indeed - and there are already exceptions in the code, for example it exempts the first word from lower-casing if the second letter is also a capital (see how crazy it is already!), but that's really a drop in the ocean of possible exemptions needed for it not to introduce more problems than it solves, plus it's just decidedly unnatural (as evidenced by the lack of this style in Symfony itself). Here are some more facetious examples:

* @param string $a Fabien's favourite colour
* @param string $a Berlin's top restaurant
* @param float $q QoS scaling factor
* @param string $s President Macron's preferred web development agency
* @param int $day Monday is the first day of the week
* @param string $cn MyClassName is the default
* @param string $n GoF pattern name

All of these would be objectively broken by this policy, and that's just in English. IMHO, these should be left untouched. As for the sentence thing, much of the the point of phpdoc is to be able to extract documentation from source and format/present it in non-code contexts, for example where the description may be presented in isolation, so preserving the intent of the author should be paramount. This is not a BC break since it only affects new code - pretty much all Symfony code already does it. Can we have an unambiguous policy statement on this please?

[nicolas-grekas]

The policy is to have an uppercase first letter but no final dot.