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

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

==== Example ====
This would allow the example above to be written as

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

?>
</PHP>

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

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

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


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

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

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