Re: DocComments for internal functions

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