Skip to content

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

@Synchro

Description

@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?

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions