Skip to content

Commit d0852d5

Browse files
chschneiderChristian SchneiderTimWollaDanielEScherzer
authored
[RFC] Add DocComments for function parameters (#21279)
RFC: https://wiki.php.net/rfc/parameter-doccomments --------- Co-authored-by: Christian Schneider <schneider@search.ch> Co-authored-by: Tim Düsterhus <tim@tideways-gmbh.com> Co-authored-by: Daniel Scherzer <daniel.e.scherzer@gmail.com>
1 parent eab1c01 commit d0852d5

16 files changed

+524
-11
lines changed

‎NEWS‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,7 @@ PHP NEWS
100100
(ilutov)
101101
. Fixed bug GH-21362 (ReflectionMethod::invoke/invokeArgs() did not verify
102102
Closure instance identity for Closure::__invoke()). (Ilia Alshanetsky)
103+
. Added ReflectionParameter::getDocComment(). (chschneider)
103104

104105
- Session:
105106
. Fixed bug 71162 (updateTimestamp never called when session data is empty).

‎UPGRADING‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -144,6 +144,8 @@ PHP 8.6 UPGRADE NOTES
144144
. ReflectionConstant::inNamespace()
145145
. Added ReflectionProperty::isReadable() and ReflectionProperty::isWritable().
146146
RFC: https://wiki.php.net/rfc/isreadable-iswriteable
147+
. Added ReflectionParameter::getDocComment().
148+
RFC: https://wiki.php.net/rfc/parameter-doccomments
147149

148150
- Intl:
149151
. `grapheme_strrev()` returns strrev for grapheme cluster unit.

‎Zend/zend_API.c‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2997,6 +2997,7 @@ ZEND_API void zend_convert_internal_arg_info(zend_arg_info *new_arg_info, const
29972997
new_arg_info->name = NULL;
29982998
new_arg_info->default_value = NULL;
29992999
}
3000+
new_arg_info->doc_comment = NULL;
30003001
new_arg_info->type = arg_info->type;
30013002
zend_convert_internal_arg_info_type(&new_arg_info->type, persistent);
30023003
}

‎Zend/zend_compile.c‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8027,6 +8027,7 @@ static void zend_compile_params(zend_ast *ast, zend_ast *return_type_ast, uint32
80278027
} else {
80288028
arg_infos->type = (zend_type) ZEND_TYPE_INIT_CODE(fallback_return_type, 0, 0);
80298029
}
8030+
arg_infos->doc_comment = NULL;
80308031
arg_infos++;
80318032
op_array->fn_flags |= ZEND_ACC_HAS_RETURN_TYPE;
80328033

@@ -8125,6 +8126,7 @@ static void zend_compile_params(zend_ast *ast, zend_ast *return_type_ast, uint32
81258126
arg_info->name = zend_string_copy(name);
81268127
arg_info->type = (zend_type) ZEND_TYPE_INIT_NONE(0);
81278128
arg_info->default_value = NULL;
8129+
arg_info->doc_comment = doc_comment_ast ? zend_string_copy(zend_ast_get_str(doc_comment_ast)) : NULL;
81288130

81298131
if (attributes_ast) {
81308132
zend_compile_attributes(

‎Zend/zend_compile.h‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -515,6 +515,7 @@ typedef struct _zend_arg_info {
515515
zend_string *name;
516516
zend_type type;
517517
zend_string *default_value;
518+
zend_string *doc_comment;
518519
} zend_arg_info;
519520

520521
/* the following structure repeats the layout of zend_internal_arg_info,

‎Zend/zend_language_parser.y‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -821,9 +821,9 @@ parameter:
821821
{ $$ = zend_ast_create_ex(ZEND_AST_PARAM, $1 | $3 | $4, $2, $5, NULL,
822822
NULL, $6 ? zend_ast_create_zval_from_str($6) : NULL, $7); }
823823
| optional_cpp_modifiers optional_type_without_static
824-
is_reference is_variadic T_VARIABLE backup_doc_comment '=' expr optional_property_hook_list
825-
{ $$ = zend_ast_create_ex(ZEND_AST_PARAM, $1 | $3 | $4, $2, $5, $8,
826-
NULL, $6 ? zend_ast_create_zval_from_str($6) : NULL, $9); }
824+
is_reference is_variadic T_VARIABLE '=' expr backup_doc_comment optional_property_hook_list
825+
{ $$ = zend_ast_create_ex(ZEND_AST_PARAM, $1 | $3 | $4, $2, $5, $7,
826+
NULL, $8 ? zend_ast_create_zval_from_str($8) : NULL, $9); }
827827
;
828828

829829
optional_type_without_static:

‎Zend/zend_opcode.c‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -648,6 +648,9 @@ ZEND_API void destroy_op_array(zend_op_array *op_array)
648648
if (arg_info[i].name) {
649649
zend_string_release_ex(arg_info[i].name, 0);
650650
}
651+
if (arg_info[i].doc_comment) {
652+
zend_string_release_ex(arg_info[i].doc_comment, 0);
653+
}
651654
zend_type_release(arg_info[i].type, /* persistent */ false);
652655
}
653656
efree(arg_info);

‎ext/opcache/zend_persist.c‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -652,6 +652,9 @@ static void zend_persist_op_array_ex(zend_op_array *op_array, zend_persistent_sc
652652
zend_accel_store_interned_string(arg_info[i].name);
653653
}
654654
zend_persist_type(&arg_info[i].type);
655+
if (arg_info[i].doc_comment) {
656+
zend_accel_store_interned_string(arg_info[i].doc_comment);
657+
}
655658
}
656659
if (op_array->fn_flags & ZEND_ACC_HAS_RETURN_TYPE) {
657660
arg_info++;

‎ext/opcache/zend_persist_calc.c‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -306,6 +306,9 @@ static void zend_persist_op_array_calc_ex(zend_op_array *op_array)
306306
ADD_INTERNED_STRING(arg_info[i].name);
307307
}
308308
zend_persist_type_calc(&arg_info[i].type);
309+
if (arg_info[i].doc_comment) {
310+
ADD_INTERNED_STRING(arg_info[i].doc_comment);
311+
}
309312
}
310313
}
311314

‎ext/reflection/php_reflection.c‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2649,6 +2649,22 @@ ZEND_METHOD(ReflectionParameter, __toString)
26492649

26502650
/* }}} */
26512651

2652+
/* {{{ Returns the doc comment for this parameter */
2653+
ZEND_METHOD(ReflectionParameter, getDocComment)
2654+
{
2655+
reflection_object *intern;
2656+
parameter_reference *param;
2657+
2658+
ZEND_PARSE_PARAMETERS_NONE();
2659+
2660+
GET_REFLECTION_OBJECT_PTR(param);
2661+
if (param->arg_info->doc_comment) {
2662+
RETURN_STR_COPY(param->arg_info->doc_comment);
2663+
}
2664+
RETURN_FALSE;
2665+
}
2666+
/* }}} */
2667+
26522668
/* {{{ Returns this parameter's name */
26532669
ZEND_METHOD(ReflectionParameter, getName)
26542670
{

0 commit comments

Comments
 (0)