Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:130678
Content-Type: text/plain;
	charset=us-ascii
Content-Transfer-Encoding: quoted-printable
Precedence: list
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3864.500.181\))
Subject: Re: [PHP-DEV] DocComments for internal functions
Date: Tue, 21 Apr 2026 11:33:41 +0200
References: <CF327F5E-E105-4405-AB05-EE4BAFFCCB56@cschneid.com>
 <2FGg02j2pKAcV7nu_mLBtetGMhhax9Ernyly_rH2jDaWzNUSlWMk7pYf4mEq9QIbuBj4tgxA9xLlTEnwPVqmxSTw558yTPNrEsk53G63xtQ=@gpb.moe>
 <30448463-1ABD-4005-89CC-3F558C7FE9B2@cschneid.com>
 <FAA5044A-D145-4972-B45A-0D4B6DCEBA6D@php.net>
 <C522ACBB-9591-405C-B8F7-00C347E29A75@cschneid.com>
To: internals@lists.php.net
In-Reply-To: <C522ACBB-9591-405C-B8F7-00C347E29A75@cschneid.com>
Message-ID: <A15EC55E-6F48-4FAB-81B8-E1A3B190DF34@cschneid.com>
From: cschneid@cschneid.com (Christian Schneider)

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:intern=
al-functions-doccomments
>>>>=20
>>>> I am not *fully* convinced that we should add DocComments for =
internal parameters/functions/classes/constants, as this feels like a =
lot of complexity.
>>>=20
>>> What kind of complexity are you thinking about? Code-wise? =
Integration into the build process?
>>=20
>> I'm wondering how much this does to increase the size of the PHP =
compiled binaries.
>=20
> 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=3D"-O3 -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=3D64"
>=20
> 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=3D'-O3 -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=3D64' \
CXXFLAGS=3D'-O3 -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=3D64' \
CPPFLAGS=3D'-O3 -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=3D64' \
'./configure' \
'--enable-bcmath' \
'--enable-debug=3Dno' \
'--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
=20
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

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:intern=
al-func-doccomments

I'd appreciate any thoughts,
- Chris