Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:130156
Feedback-ID: i8414410d:Fastmail
Precedence: list
MIME-Version: 1.0
Date: Tue, 24 Feb 2026 13:13:05 -0600
To: "php internals" <internals@lists.php.net>
Message-ID: <5706932f-e005-41cc-8bc5-1fb1fa4e344c@app.fastmail.com>
In-Reply-To: <65C41C15-74C2-4A25-ABA7-056D612DF366@cschneid.com>
References: <24229A82-F5BF-48F2-9E6C-FE45A99FB9E9@cschneid.com>
 <c8086cca-ada0-4f74-8f5c-bb4f1b60b723@bastelstu.be>
 <65C41C15-74C2-4A25-ABA7-056D612DF366@cschneid.com>
Subject: Re: [PHP-DEV] [RFC] DocComments For Function Parameters
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
From: larry@garfieldtech.com ("Larry Garfield")

On Mon, Feb 23, 2026, at 11:32 AM, Christian Schneider wrote:
> Am 22.02.2026 um 18:52 schrieb Tim D=C3=BCsterhus <tim@bastelstu.be>:
>> - Please add a link to the ML discussion to the =E2=80=9CReferences=E2=
=80=9D section: https://news-web.php.net/php.internals/130121
>>=20
>> - The ABI change is irrelevant: Extensions have to be recompiled for =
every PHP branch and new features may not ship with 3rd-digit versions a=
nyways. Mentioning this is thus misleading at best (affecting =E2=80=9CB=
ackwards incompatible changes=E2=80=9D, =E2=80=9CProposed PHP version=E2=
=80=9D, and =E2=80=9CRFC Impact=E2=80=9D).
>>=20
>> - In fact, there is not even an ABI change, because the new field is =
added at the end of the struct.
>>=20
>> - Within the =E2=80=9CEcosystem=E2=80=9D impact, you should probably =
mention that this might require adjustments to code style / formatting g=
uidelines 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=20
> 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 incon=
sistent.  I've... never actually seen someone do that.  I have seen peop=
le put doc comments on the line before a parameter (which I then had to =
move to the function docblock, which was annoying).  Every other docbloc=
k-able construct has the docblock as a prefix, not suffix.  It should be=
 a prefix here as well. =20

I'm not sure I can support it as a suffix because it would be so inconsi=
stent, and would essentially mandate same-line comments rather than comm=
ent on own line.  Bear in mind, the parameter line could be quite long i=
n a constructor, and the description itself can be quite long, too.

public function __construct(
    public final readonly SomeVerboselyNamedClass $thingie /** We have b=
arely any room here. */

// vs

    /**
     * We have plenty of room here, and can easily go to multiple lines =
if necessary in context.=20
     * Which it often is.
     */
    public final readonly SomeVerboselyNamedClass $thingie /** We have b=
arely any room here. */
) {}

Prefix docblock is the way to go.

2. I realize the existing getDocComment() implementations also use strin=
g|false, but at what point are we going to accept that is a stupid retur=
n type and use string|null instead? :-(  (I realize it may not be fixabl=
e here; I just want to whine about that design flaw propagating even fur=
ther.)

--Larry Garfield