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:internal-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
