Re: [RFC] DocComments For Function Parameters

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