PHP RFC: DocComments For Function Parameters

• Version: 1.0.1
• Date: 2026-02-23
• Author: Christian Schneider, cschneid@cschneid.com
• Status: Voting
• Implementation: https://github.com/php/php-src/pull/21279
• Discussion thread: https://news-web.php.net/php.internals/130121

PHP supports DocComments with the getDocComment() function in various Reflection classes but not in ReflectionParameter.

Function parameters are currently documented with @param in the function DocComment block:

/**
* Search for entries matching query
* @param string $query  Terms to search for in database
* @param int $num  Maximum number of entries returned, default is 10
*/
function search(string $query, int $num = 10)
{
  ...
}

The downside of this is that the parameters and their types have to be mentioned twice (DocComment and parameter list) and the documentation can diverge from the implementation.

We propose adding DocComment support for function parameters (all the way to the end of the parameter definition, i.e. up to the comma starting the next parameter) and a new function in the ReflectionParameter class

public function getDocComment(): string|false {}

This would allow the example above to be written as

<?php
 
/** Search for entries matching query */
function search(
  /** Terms to search for in database    */
  string $query,
  /** Maximum number of entries returned */
  int $num = 10
) {
  return ['foo', 'bar', 'qux'];
}
 
foreach (new ReflectionFunction("search")->getParameters() as $p) {
  echo $p->name . ": " . $p->getDocComment() . "\n";
}
 
?>

This would output

query: /** Terms to search for in database    */
num: /** Maximum number of entries returned */

The proposal also allows to write the DocComment behind the parameter definition but before the comma starting the next parameter (this is similar to and already supported for property definitions):

<?php
 
/** Search for entries matching query */
function search(
  string $query /** Terms to search for in database    */,
  int $num = 10 /** Maximum number of entries returned */
) {
  ...
}
?>

None.

Next PHP 8.x (8.6).

Allowing more local, less redundant and less error-prone documentation of function parameters should enable better documentation. This might impact code style / formatting guidelines and auto formatter configurations and has to be decided in the respective communities.

None.

None.

None.

None.

Primary Vote requiring a 2/3 majority to accept the RFC:

Add DocComment support to function parameters as outlined in the RFC?
Real name	Yes	No	Abstain
ayesh
derick
dharman
iliaa
ilutov
kalle
ocramius
pmjones
ramsey
theodorejb
timwolla
weierophinney
Count:	11	0	1
This poll will close on 2026-03-31 00:00:00 UTC.

https://github.com/php/php-src/pull/21279

None.

None.

• 2026-02-21 Initial
• 2026-02-22 Add link to discussion mailing list thead, remove part about ABI change
• 2026-02-23 Add implementation PR and test for new function
• 2026-02-25 Adapt examples to show DocComment before / after parameter