====== 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

===== 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:
<PHP>
/**
* 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)
{
  ...
}
</PHP>

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
<PHP>
public function getDocComment(): string|false {}
</PHP>

 which would allow the example above to be written as

==== Examples ====
<PHP>
<?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";
}

?>
</PHP>

This would output
<file>
query: /** Terms to search for in database    */
num: /** Maximum number of entries returned */
</file>

===== Backward Incompatible Changes =====
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.

===== Proposed PHP Version(s) =====
Next PHP 8.x (8.6) due to the ABI change.

===== RFC Impact =====
==== To the Ecosystem ====
Allowing more local, less redundant and less error-prone documentation of function parameters should enable better documentation.

==== To Existing Extensions ====
Existing extentions have to be recompiled due to the ABI change.

==== To SAPIs ====
None.

===== Open Issues =====
Write tests for ReflectionParameter::getDocComment()

===== Future Scope =====
None.

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

<doodle title="Add DocComment support to function parameters as outlined in the RFC?" voteType="single" closed="true" closeon="2026-01-01T15:30:00Z">
   * Yes
   * No
   * Abstain
</doodle>

===== Patches and Tests =====
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

===== Implementation =====

===== References =====
None.

===== Rejected Features =====
None.

===== Changelog =====
None.