DocComments For Function Parameters View as Markdown

Introduction

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.

Proposal

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

Example

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

Example with DocComment after Parameter

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 */
) {
  ...
}
?>

Backward Incompatible Changes

None.

Proposed PHP Version(s)

Next PHP 8.x (8.6).

RFC Impact

To the Ecosystem

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.

To Existing Extensions

None.

To SAPIs

None.

Open Issues

None.

Future Scope

None.

Voting Choices

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

Vote: Add DocComment support to function parameters as outlined in the RFC? — Yes: 23 · No: 0 · Abstain: 4 (closed)

Implementation

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

References

None.

Rejected Features

None.

Changelog

• 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