Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:130053
Content-Type: text/plain;
	charset=us-ascii
Content-Transfer-Encoding: quoted-printable
Precedence: list
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3864.300.41.1.7\))
Subject: [PHP-DEV] Function/Method parameter DocComments
Message-ID: <F8B154EE-9156-471F-B59C-9F06B016B96D@cschneid.com>
Date: Sun, 8 Feb 2026 13:48:10 +0100
To: PHP internals list <internals@lists.php.net>
From: cschneid@cschneid.com (Christian Schneider)

I have a proposal where I wanted to check the mood first before I write =
an RFC.

Background:
While looking into better documenting our Web APIs we figured our =
preferred solution is parameter typing plus DocComments and do both =
basic checks on input values (e.g. string vs. int vs. array) and =
automatically generate OpenAPI docs.

So we ended up with something like

/**
 * Search for entries matching query
 * @param $query  Terms to search for in database
 * @param $num  Maximum number of entries returned, default is 10
 */
function api_search(string $query, ?int $num =3D 10) { ... }

The downside of this is that the parameters have to be mentioned twice =
(DocComment and parameter list) and the documentation can diverge from =
the implementation.

So we looked into using parameters DocComments like
/**
 * Search for entries matching query
 */
function api_search(
	string $query  /** Terms to search for in database */,
	?int $num =3D 10 /** Maximum number of entries returned */,
) { ... }
and realized that this is currently not supported.

Part 1:
When I looked at the parser I realized that PHP already had the syntax =
in place for this and it was only missing
a) storing the DocComments with the parameters (zend_arg_info)
b) providing a method getDocComment() in ReflectionParameter
c) allowing DocComments *behind* the parameter instead of before them.

While part a) and b) are pretty straightforward I also slightly changed =
the syntax to allow the DocComments *after* the parameter definition but =
*before* the comma starting the next parameter. This keeps the =
implementation very simple with the limitation of having to move the =
comma behind the DocComment.
Rationale for c) We strongly favored the comment to be behind instead of =
before the parameter name + default value and found the trailing comma a =
valid compromise.

Part 2:
I realized that PHP already had (almost) everything in place to also =
have DocComments for the internal functions.
So I extended zend_internal_arg_info and zend_internal_function_info to =
allow this.

Part 3:
Then I went down the rabbit hole and wrote a script to extract the =
information from the doc-en DocBook source and add them to the stub =
files.
To do this I added a script build/add_doccomments.php and changed =
gen_stub.php to use the new macros when applicable.

Implementation:
You can find the code at
	=
https://github.com/php/php-src/compare/master...chschneider:php-src:param-=
doccomment-all
with the 3 first commits representing the 3 parts above and the 4th =
commit containing the files automatically generated by the =
add_doccomments.php and gen_stub.php build scripts so you don't need to =
run them.

Missing part:
- Add tests for ReflectionParameter::getDocComment()
- Include add_doccomments.php in the build process, currently is has to =
be called manually.

Backwards compatibility:
As I added a field to the Zend arg_info structure it is an ABI change =
which needs external modules to be recompiled to match it.
I assume this is acceptable for PHP 8.6, correct?
Otherwise the only change is the additional method getDocComment() for =
ReflectionParameter, everything else is backwards compatible.

Is there interest in the community to add this to the next PHP version?
Should I rewrite this into an RFC or are the other =
comments/recommendations before I do that?

Regards,
- Chris