Am 10.04.2026 um 23:47 schrieb Christian Schneider <[email protected]>:
> Am 10.04.2026 um 17:40 schrieb Derick Rethans <[email protected]>:
>> On 10 April 2026 15:21:34 BST, Christian Schneider <[email protected]>
>> wrote:
>>> Am 10.04.2026 um 12:54 schrieb Gina P. Banyard <[email protected]>:
>>>> On Thursday, 9 April 2026 at 14:33, Christian Schneider
>>>> <[email protected]> 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
