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? 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
