[RFC] DocComments For Function Parameters

Hi

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

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