Everything

php

[RFC] DocComments For Function Parameters

php.internals

Christian Schneider

192 days ago

I would like to introduce DocComment support for function parameters:

https://wiki.php.net/rfc/parameter-doccomments

Regards,
- Chris

Matthew Weier O'Phinney

192 days ago

On Sat, Feb 21, 2026, 11:52 AM Christian Schneider <cschneid@cschneid.com>
wrote:

> I would like to introduce DocComment support for function parameters:
>
> https://wiki.php.net/rfc/parameter-doccomments
>
>

I've been wanting this for nearly 20 years!

Questions:

- Would it also support the comment appearing before the parameter?

/** This is the description */
string $message,

- If so, what would be the behavior of the engine if a docblock was present
in both positions, like:

/** This is the description */
$message
/** But what about this? */,

Generally, docblocks precede the item being documented, so if only one form
were allowed, for consistency, that should be the form supported.

--
Matthew Weier O'Phinney
mweierophinney@gmail.com
https://mwop.net/
he/him

Christian Schneider

191 days ago

Am 21.02.2026 um 19:41 schrieb Matthew Weier O'Phinney <mweierophinney@gmail.com>:

> - Would it also support the comment appearing before the parameter?
>
>     /** This is the description */
>     string $message,

Yes, this works.

> - If so, what would be the behavior of the engine if a docblock was present in both positions, like:
>
>     /** This is the description */
>     $message
>     /** But what about this? */,

The last DocComment wins, the same as for the current

class A
{
/** a */ public /** b */ int /** c */ $property /** d */;
}

echo (new ReflectionClass('A'))->getProperties()[0]->getDocComment();

This outputs the last one (/** d */), see https://3v4l.org/PZFHD

Regards,
- Chris

Tim Düsterhus

191 days ago

Hi

On 2/21/26 18:51, Christian Schneider wrote:

> I would like to introduce DocComment support for function parameters:
>
> https://wiki.php.net/rfc/parameter-doccomments

Thank you. This makes sense to me and it has a straight-forward
implementation.

Some comments regarding the RFC:

- 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.

Best regards
Tim Düsterhus

Christian Schneider

190 days ago

Am 22.02.2026 um 18:52 schrieb Tim Düsterhus <tim@bastelstu.be>:

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

Tim Düsterhus

190 days ago

Hi

On 2/23/26 18:32, Christian Schneider wrote:

> I changed the RFC accordingly and also added an implementation PR and a test and I would consider it ready.

Thank you. No further comments from my side.

Best regards
Tim Düsterhus

Larry Garfield

189 days ago

On Mon, Feb 23, 2026, at 11:32 AM, Christian Schneider wrote:

> Am 22.02.2026 um 18:52 schrieb Tim Düsterhus <tim@bastelstu.be>:
>> - 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

Christian Schneider

188 days ago

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

Christian Schneider

188 days ago

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

Larry Garfield

186 days ago

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

Christian Schneider

174 days ago

Am 21.02.2026 um 18:51 schrieb Christian Schneider <cschneid@cschneid.com>:

> I would like to introduce DocComment support for function parameters:
>
> https://wiki.php.net/rfc/parameter-doccomments

I intend to open the voting for the DocComment support RFC on Friday, March 13. This serves as the "Intent to Vote" message.

If there are any questions or concerns regarding the RFC, please raise them at this time, so I can clarify or make any changes, as needed.

Regards,
Chris