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
- extended zend_internal_arg_info and zend_internal_function_info
- added macros like ZEND_ARG_INFO_DOCCOMMENT to zend_API.h
- added a script build/add_doccomments.php to extract the documentation from a doc-en (or other language) checkout
- 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
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
- extended zend_internal_arg_info and zend_internal_function_info
- added macros like ZEND_ARG_INFO_DOCCOMMENT to zend_API.h
- added a script build/add_doccomments.php to extract the documentation from a doc-en (or other language) checkout
- 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 --forceThe implementation can be examined at
https://github.com/php/php-src/compare/master...chschneider:php-src:internal-functions-doccommentsQuestions:
- 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
Am 10.04.2026 um 12:54 schrieb Gina P. Banyard internals@gpb.moe:
The implementation can be examined at
https://github.com/php/php-src/compare/master...chschneider:php-src:internal-functions-doccommentsI 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: https://github.com/chschneider/lsp_php
Regards,
- Chris
Am 10.04.2026 um 12:54 schrieb Gina P. Banyard internals@gpb.moe:
The implementation can be examined at
https://github.com/php/php-src/compare/master...chschneider:php-src:internal-functions-doccommentsI 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:
Am 10.04.2026 um 12:54 schrieb Gina P. Banyard internals@gpb.moe:
The implementation can be examined at
https://github.com/php/php-src/compare/master...chschneider:php-src:internal-functions-doccommentsI 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
Am 10.04.2026 um 23:47 schrieb Christian Schneider cschneid@cschneid.com:
Am 10.04.2026 um 17:40 schrieb Derick Rethans derick@php.net:
Am 10.04.2026 um 12:54 schrieb Gina P. Banyard internals@gpb.moe:
The implementation can be examined at
https://github.com/php/php-src/compare/master...chschneider:php-src:internal-functions-doccommentsI 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.
I checked again for more extensions (end hence more doc comments) enabled and surprisingly the difference was not as big as I first reported.
Here are the configure options I used:
CFLAGS='-O3 -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64'
CXXFLAGS='-O3 -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64'
CPPFLAGS='-O3 -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64'
'./configure'
'--enable-bcmath'
'--enable-debug=no'
'--enable-exif'
'--enable-intl'
'--enable-pcntl'
'--enable-soap'
'--with-zip'
'--enable-mbstring'
'--with-curl'
'--with-freetype'
'--enable-gd'
'--with-gettext'
'--with-iconv'
'--with-jpeg'
'--with-webp'
'--with-ldap'
'--with-mysqli'
'--with-openssl'
'--with-pear'
'--with-pgsql'
'--with-pdo-mysql'
'--with-zlib' \
Result:
a) No file size difference!? Not 100% what that means:
$ ls -l php.{master,doccomments}
-rwxrwxr-x 1 cschneid trusted 32287008 Apr 21 10:55 php.doccomments
-rwxrwxr-x 1 cschneid trusted 32287008 Apr 21 10:55 php.master
b) About 500k difference in the .rodata segment:
$ diff -u <(eu-size -d -A php.master) <(eu-size -d -A php.doccomments)
-php.master:
+php.doccomments:
-.text 8629549 6322432
+.text 8629293 6322432
-.rodata 14933412 18874368
+.rodata 15459140 18874368
-.eh_frame_hdr 163060 33807780
+.eh_frame_hdr 163052 34333508
-.eh_frame 955472 33970840
+.eh_frame 955424 34496560
-Total 26223763
+Total 26749179
============
Now so far I got no input in how to proceed: Should I create an RFC or directly a PR?
I see the following possible outcomes:
- The whole idea is rejected by the maintainers / community
- The foundation to generate PHP binaries with doc comments for internal functions is added and documented but not enabled
- In addition to 2) before each release the doc comments are generated / updated from the current doc-en repository (and committed?)
Adding doc comments to the source currently requires calling
./build/add_doccomments.php && ./build/gen_stub.php --force
The current implementation can be examined at
https://github.com/php/php-src/compare/master...chschneider:php-src:internal-func-doccomments
I'd appreciate any thoughts,
- Chris