Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:130178
Feedback-ID: i8414410d:Fastmail
Precedence: list
MIME-Version: 1.0
Date: Thu, 26 Feb 2026 14:17:17 -0600
To: "php internals" <internals@lists.php.net>
Message-ID: <09ff54b3-5d13-4017-b867-4b2dda837624@app.fastmail.com>
In-Reply-To: <AF068A60-C91E-4071-BF7E-C9A73BB096D7@cschneid.com>
References: <24229A82-F5BF-48F2-9E6C-FE45A99FB9E9@cschneid.com>
 <c8086cca-ada0-4f74-8f5c-bb4f1b60b723@bastelstu.be>
 <65C41C15-74C2-4A25-ABA7-056D612DF366@cschneid.com>
 <5706932f-e005-41cc-8bc5-1fb1fa4e344c@app.fastmail.com>
 <4BCFFC1C-7F82-40FF-ADEE-E8161C05047D@cschneid.com>
 <AF068A60-C91E-4071-BF7E-C9A73BB096D7@cschneid.com>
Subject: Re: [PHP-DEV] [RFC] DocComments For Function Parameters
Content-Type: text/plain
Content-Transfer-Encoding: 7bit
From: larry@garfieldtech.com ("Larry Garfield")

On Tue, Feb 24, 2026, at 6:18 PM, Christian Schneider wrote:
> Am 24.02.2026 um 21:53 schrieb Christian Schneider <cschneid@cschneid.com>:
>> Am 24.02.2026 um 20:13 schrieb Larry Garfield <larry@garfieldtech.com>:
>>> 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.  
>> 
>> Just to clarify: You can write it before, in the middle or after the parameter, just like you can write it before or in the middle of properties.
>> The proposal allows pre, middle and post styles.
>
> I changed the example to use the standard docblock-before variant and 
> added a separate example to explain the option to put the comments 
> behind the parameter definition:
> 	https://wiki.php.net/rfc/parameter-doccomments#example
>
> Regards,
> - Chris

Huh.  I had no idea that a suffix was possible for properties at all.  I've literally never seen that.  TIL.

Given that, and that the RFC is now promoting the prefix style, I am now in support.

One additional note: In the updated suffix section, it would be good to note that is similar to properties, which already support a suffix even if it's hardly ever used.  I think it's likely that many others also don't realize it's already possible.  Also, there's a missing period after "next parameter."  :-)

--Larry Garfield