Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:130601
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: Fri, 10 Apr 2026 16:21:34 +0200
References: <CF327F5E-E105-4405-AB05-EE4BAFFCCB56@cschneid.com>
 <2FGg02j2pKAcV7nu_mLBtetGMhhax9Ernyly_rH2jDaWzNUSlWMk7pYf4mEq9QIbuBj4tgxA9xLlTEnwPVqmxSTw558yTPNrEsk53G63xtQ=@gpb.moe>
To: PHP internals list <internals@lists.php.net>
In-Reply-To: <2FGg02j2pKAcV7nu_mLBtetGMhhax9Ernyly_rH2jDaWzNUSlWMk7pYf4mEq9QIbuBj4tgxA9xLlTEnwPVqmxSTw558yTPNrEsk53G63xtQ=@gpb.moe>
Message-ID: <30448463-1ABD-4005-89CC-3F558C7FE9B2@cschneid.com>
From: cschneid@cschneid.com (Christian Schneider)

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.

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.
>=20
> 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