Everything

php

DocComments for internal functions

php.internals

Christian Schneider

145 days ago

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

Gina P. Banyard

144 days ago

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

Christian Schneider

144 days ago

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
>> https://github.com/php/php-src/compare/master...chschneider:php-src:internal-functions-doccomments
>
> 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: https://github.com/chschneider/lsp_php

Regards,
- Chris

Derick Rethans

144 days ago

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
>>> https://github.com/php/php-src/compare/master...chschneider:php-src:internal-functions-doccomments
>>
>> 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

Christian Schneider

143 days ago

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
>>>> https://github.com/php/php-src/compare/master...chschneider:php-src:internal-functions-doccomments
>>>
>>> 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

Christian Schneider

133 days ago

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>:
>> 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
>>>>> https://github.com/php/php-src/compare/master...chschneider:php-src:internal-functions-doccomments
>>>>
>>>> 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.

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:
1) The whole idea is rejected by the maintainers / community
2) The foundation to generate PHP binaries with doc comments for internal functions is added and documented but not enabled
3) 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