Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:130163
Content-Type: text/plain;
	charset=us-ascii
Content-Transfer-Encoding: quoted-printable
Precedence: list
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3864.400.21\))
Subject: Re: [PHP-DEV] [RFC] DocComments For Function Parameters
Date: Tue, 24 Feb 2026 21:53:55 +0100
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>
To: php internals <internals@lists.php.net>
In-Reply-To: <5706932f-e005-41cc-8bc5-1fb1fa4e344c@app.fastmail.com>
Message-ID: <4BCFFC1C-7F82-40FF-ADEE-E8161C05047D@cschneid.com>
From: cschneid@cschneid.com (Christian Schneider)

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. =20

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 understand that putting it after the parameter is not to everybody's =
taste but is the fact that this proposal *allows* it to be after a =
deal-breaker?

If people feel really strongly about not allowing this (but why didn't =
anyone ever complain about in-the-middle doccomments for properties etc. =
so far?) then I could adapt the proposal. I'm not yet convinced of the =
harm though.

> 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.)

I agree that anything|false is most of the time a mistake (as the =
absence of a value is better expressed by null) but I doubt we should =
change that for this single case only. If we want to change this then it =
should be a proposal for a whole range of functions, or in this case at =
least for getDocComment() in all Reflection classes.

Regards,
- Chris