Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:130600
Date: Fri, 10 Apr 2026 10:54:03 +0000
To: Christian Schneider <cschneid@cschneid.com>
Cc: PHP internals list <internals@lists.php.net>
Subject: Re: [PHP-DEV] DocComments for internal functions
Message-ID: <2FGg02j2pKAcV7nu_mLBtetGMhhax9Ernyly_rH2jDaWzNUSlWMk7pYf4mEq9QIbuBj4tgxA9xLlTEnwPVqmxSTw558yTPNrEsk53G63xtQ=@gpb.moe>
In-Reply-To: <CF327F5E-E105-4405-AB05-EE4BAFFCCB56@cschneid.com>
References: <CF327F5E-E105-4405-AB05-EE4BAFFCCB56@cschneid.com>
Feedback-ID: 96993444:user:proton
Precedence: list
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
From: internals@gpb.moe ("Gina P. Banyard")

On Thursday, 9 April 2026 at 14:33, Christian Schneider <cschneid@cschneid.=
com> wrote:

> As a follow-up to the now-merged DocComments for function parameters I wo=
uld like to propose annotating internal functions with DocComments automati=
cally generated from the documentation.
>=20
> This would benefit e.g. LSPs and static analysers written in PHP to use r=
eflection to show (a minimal) documentation for internal (e.g. strlen), bas=
ic (e.g. str_replace) and bundled extension functions (e.g. grapheme_strlen=
).
>=20
> To this end I
> 1) extended zend_internal_arg_info and zend_internal_function_info
> 2) added macros like ZEND_ARG_INFO_DOCCOMMENT to zend_API.h
> 3) added a script build/add_doccomments.php to extract the documentation =
from a doc-en (or other language) checkout
> 4) extended build/gen_stub.php to generate the new ZEND_ARG_INFO_*_DOCCOM=
MENT macros for @genstubs-expose-comment-block
>=20
> With this in place one can generate the internal doc comments with
> =09./build/add_doccomments.php
> =09./build/gen_stub.php --force
>=20
> The implementation can be examined at
> =09https://github.com/php/php-src/compare/master...chschneider:php-src:in=
ternal-functions-doccomments
>=20
> Questions:
> - Is there interest in adding this feature?
> - How should it be integrated into the build process? A simple version wo=
uld be to run the two scripts (with doc-en) before generating a release, a =
more complicated version could add a configure option to also be able to ch=
ose a local documentation checkout (e.g. for a different language)
> - Does this require an RFC or should this be discussed here and (in case =
there is interest) in a PR I would create?
>=20
> Regards,
> - Chris
>=20

I am not *fully* convinced that we should add DocComments for internal para=
meters/functions/classes/constants, as this feels like a lot of complexity.
However, I've been working for the last 2ish years on some tooling [1] to i=
mprove the syncing of the manual from the stubs, and in the long run being =
able to semi-automatically create the migration guide.

Considering that a large part of it is parsing the documentation and the st=
ubs into a common representation to be able to do diffs on them, this might=
 be useful if we somehow want to "augment" the stubs.


Best regards,

Gina P. Banyard


[1] https://github.com/Girgias/stub-to-docbook