PHP RFC: DocComments For Function Parameters

• Version: 0.9
• Date: 2026-02-21
• Author: Christian Schneider, cschneid@cschneid.com
• Status: Under Discussion
• Implementation: https://github.com/php/php-src/compare/master...chschneider:php-src:param-doccomment-part1

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

which would allow the example above to be written as

<?php
 
/** Search for entries matching query */
function search(
  $query        /** Terms to search for in database    */,
  int $num = 10 /** Maximum number of entries returned */,
) {
  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 change is Userland API and Internal API compatible. As it adds a field to the arg_info structure it breaks ABI compatibility and extensions have to be recompiled.

Next PHP 8.x (8.6) due to the ABI change.

Allowing more local, less redundant and less error-prone documentation of function parameters should enable better documentation.

Existing extentions have to be recompiled due to the ABI change.

None.

Write tests for ReflectionParameter::getDocComment()

None.

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

There is currently no PR but only an experimental branch to be converted into a PR: https://github.com/php/php-src/compare/master...chschneider:php-src:param-doccomment-part1

None.

None.

None.