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
Comparing php:master...chschneider:internal-functions-doccomments · php/php-src · GitHub
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
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
Comparing php:master...chschneider:internal-functions-doccomments · php/php-src · GitHub
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] GitHub - Girgias/stub-to-docbook: Generate and update DocBook PHP documentation sources according to php-src stubs · GitHub
Am 10.04.2026 um 12:54 schrieb Gina P. Banyard <internals@gpb.moe>:
On Thursday, 9 April 2026 at 14:33, Christian Schneider <cschneid@cschneid.com> wrote:
The implementation can be examined at
Comparing php:master...chschneider:internal-functions-doccomments · php/php-src · GitHub
I am not *fully* convinced that we should add DocComments for internal parameters/functions/classes/constants, as this feels like a lot of complexity.
What kind of complexity are you thinking about? Code-wise? Integration into the build process?
The infrastructure in the code (zend_API and gen_stub.php) is almost ready.
Sure, my script in build/add_doccomments.php might have some rough edges but I wouldn't consider it that complex either.
It's like one screenful of code - at least for my not too big screen size 
- for usage/option handling, one screen of documentation parsing and one screen of adding/replacing them in the stub.php files.
Side-note: The documentation parsing code has a very simplistic check feature so see if all parameters have types and descriptions and it might be interesting to expand on that but then it would belong in the doc-en repository, not the php-src one.
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.
It seem you are trying to do something more complicated than me (going from stubs to documentation) but I think they are still somewhat separate things even though they might both work on php-src and doc-en.
My motivation for adding documentation for internal functions is based eating my own dog food when using my minimalistic single-file LSP written in PHP which uses Reflection to provide auto-completions and documentation which can be found here: GitHub - chschneider/lsp_php: Language Server Protocol server for PHP written in PHP · GitHub
Regards,
- Chris
On 10 April 2026 15:21:34 BST, Christian Schneider <cschneid@cschneid.com> wrote:
Am 10.04.2026 um 12:54 schrieb Gina P. Banyard <internals@gpb.moe>:
On Thursday, 9 April 2026 at 14:33, Christian Schneider <cschneid@cschneid.com> wrote:
The implementation can be examined at
Comparing php:master...chschneider:internal-functions-doccomments · php/php-src · GitHub
I am not *fully* convinced that we should add DocComments for internal parameters/functions/classes/constants, as this feels like a lot of complexity.
What kind of complexity are you thinking about? Code-wise? Integration into the build process?
I'm wondering how much this does to increase the size of the PHP compiled binaries.
cheers
Derick
Am 10.04.2026 um 17:40 schrieb Derick Rethans <derick@php.net>:
On 10 April 2026 15:21:34 BST, Christian Schneider <cschneid@cschneid.com> wrote:
Am 10.04.2026 um 12:54 schrieb Gina P. Banyard <internals@gpb.moe>:
On Thursday, 9 April 2026 at 14:33, Christian Schneider <cschneid@cschneid.com> wrote:
The implementation can be examined at
Comparing php:master...chschneider:internal-functions-doccomments · php/php-src · GitHub
I am not *fully* convinced that we should add DocComments for internal parameters/functions/classes/constants, as this feels like a lot of complexity.
What kind of complexity are you thinking about? Code-wise? Integration into the build process?
I'm wondering how much this does to increase the size of the PHP compiled binaries.
On my machine it adds about 2M (7%) as the sapi/cli/php binary increases from ~28M to ~30M for a build with default ./configure and
CFLAGS="-O3 -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64"
I would assume this is mostly in a read-only data section and hence shareable between processes.
- Chris