On Thursday, 9 April 2026 at 14:33, Christian Schneider <[email protected]> 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
