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:
None.
None.