Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:130595
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: [PHP-DEV] DocComments for internal functions
Message-ID: <CF327F5E-E105-4405-AB05-EE4BAFFCCB56@cschneid.com>
Date: Thu, 9 Apr 2026 15:29:58 +0200
To: PHP internals list <internals@lists.php.net>
From: cschneid@cschneid.com (Christian Schneider)

As a follow-up to the now-merged DocComments for function parameters I =
would like to propose annotating internal functions with DocComments =
automatically generated from the documentation.

This would benefit e.g. LSPs and static analysers written in PHP to use =
reflection to show (a minimal) documentation for internal (e.g. strlen), =
basic (e.g. str_replace) and bundled extension functions (e.g. =
grapheme_strlen).

To this end I
1) extended zend_internal_arg_info and zend_internal_function_info
2) added macros like ZEND_ARG_INFO_DOCCOMMENT to zend_API.h
3) added a script build/add_doccomments.php to extract the documentation =
from a doc-en (or other language) checkout
4) extended build/gen_stub.php to generate the new =
ZEND_ARG_INFO_*_DOCCOMMENT macros for @genstubs-expose-comment-block

With this in place one can generate the internal doc comments with
	./build/add_doccomments.php
	./build/gen_stub.php --force

The implementation can be examined at
	=
https://github.com/php/php-src/compare/master...chschneider:php-src:intern=
al-functions-doccomments

Questions:
- Is there interest in adding this feature?
- How should it be integrated into the build process? A simple version =
would be to run the two scripts (with doc-en) before generating a =
release, a more complicated version could add a configure option to also =
be able to chose a local documentation checkout (e.g. for a different =
language)
- Does this require an RFC or should this be discussed here and (in case =
there is interest) in a PR I would create?

Regards,
- Chris