Re: DocComments for internal functions

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 would like to propose > annotating internal functions with DocComments automatically generated from the documentation. > > This would benefit e.g. LSPs and static analysers written in PHP to use reflection to show (a > minimal) documentation for internal (e.g. strlen), basic (e.g. str_replace) and bundled extension > functions (e.g. grapheme_strlen). > > 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_*_DOCCOMMENT macros for > @genstubs-expose-comment-block > > With this in place one can generate the internal doc comments with > ./build/add_doccomments.php > ./build/gen_stub.php --force > > The implementation can be examined at > > https://github.com/php/php-src/compare/master...chschneider:php-src:internal-functions-doccomments > > Questions: > - Is there interest in adding this feature? > - How should it be integrated into the build process? A simple version would 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 chose 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? > > Regards, > - Chris > I am not *fully* convinced that we should add DocComments for internal parameters/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 improve 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 stubs 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