On Mon, Feb 23, 2026, at 11:32 AM, Christian Schneider wrote:
> Am 22.02.2026 um 18:52 schrieb Tim Düsterhus <[email protected]>:
>> - Please add a link to the ML discussion to the “References” section:
>> https://news-web.php.net/php.internals/130121
>>
>> - The ABI change is irrelevant: Extensions have to be recompiled for every
>> PHP branch and new features may not ship with 3rd-digit versions anyways.
>> Mentioning this is thus misleading at best (affecting “Backwards
>> incompatible changes”, “Proposed PHP version”, and “RFC Impact”).
>>
>> - In fact, there is not even an ABI change, because the new field is added
>> at the end of the struct.
>>
>> - Within the “Ecosystem” impact, you should probably mention that this might
>> require adjustments to code style / formatting guidelines and autoformatters
>> - or at the very least a decision needs to be made there.
>
> Thanks for this feedback.
> I changed the RFC accordingly and also added an implementation PR and a
> test and I would consider it ready.
>
> RFC: https://wiki.php.net/rfc/parameter-doccomments
> PR: https://github.com/php/php-src/pull/21279
>
> Regards,
> - Chris
I'm in favor in principle, but have 2 major pushbacks.
1. As Matthew said, putting the doc comment after the parameter is
inconsistent. I've... never actually seen someone do that. I have seen people
put doc comments on the line before a parameter (which I then had to move to
the function docblock, which was annoying). Every other docblock-able
construct has the docblock as a prefix, not suffix. It should be a prefix here
as well.
I'm not sure I can support it as a suffix because it would be so inconsistent,
and would essentially mandate same-line comments rather than comment on own
line. Bear in mind, the parameter line could be quite long in a constructor,
and the description itself can be quite long, too.
public function __construct(
public final readonly SomeVerboselyNamedClass $thingie /** We have barely
any room here. */
// vs
/**
* We have plenty of room here, and can easily go to multiple lines if
necessary in context.
* Which it often is.
*/
public final readonly SomeVerboselyNamedClass $thingie /** We have barely
any room here. */
) {}
Prefix docblock is the way to go.
2. I realize the existing getDocComment() implementations also use
string|false, but at what point are we going to accept that is a stupid return
type and use string|null instead? :-( (I realize it may not be fixable here; I
just want to whine about that design flaw propagating even further.)
--Larry Garfield
