Add DocComments for function parameters

Author: Christian Schneider

Zend/zend_API.c

@@ -2997,6 +2997,7 @@ ZEND_API void zend_convert_internal_arg_info(zend_arg_info *new_arg_info, const
 		new_arg_info->name = NULL;
 		new_arg_info->default_value = NULL;
 	}
+	new_arg_info->doc_comment = NULL;
 	new_arg_info->type = arg_info->type;
 	zend_convert_internal_arg_info_type(&new_arg_info->type, persistent);
 }

Zend/zend_compile.c

@@ -8024,6 +8024,7 @@ static void zend_compile_params(zend_ast *ast, zend_ast *return_type_ast, uint32
 		} else {
 			arg_infos->type = (zend_type) ZEND_TYPE_INIT_CODE(fallback_return_type, 0, 0);
 		}
+		arg_infos->doc_comment = NULL;
 		arg_infos++;
 		op_array->fn_flags |= ZEND_ACC_HAS_RETURN_TYPE;
 
@@ -8122,6 +8123,7 @@ static void zend_compile_params(zend_ast *ast, zend_ast *return_type_ast, uint32
 		arg_info->name = zend_string_copy(name);
 		arg_info->type = (zend_type) ZEND_TYPE_INIT_NONE(0);
 		arg_info->default_value = NULL;
+		arg_info->doc_comment = doc_comment_ast ? zend_string_copy(zend_ast_get_str(doc_comment_ast)) : NULL;
 
 		if (attributes_ast) {
 			zend_compile_attributes(

Zend/zend_compile.h

@@ -515,6 +515,7 @@ typedef struct _zend_arg_info {
 	zend_string *name;
 	zend_type type;
 	zend_string *default_value;
+	zend_string *doc_comment;
 } zend_arg_info;
 
 /* the following structure repeats the layout of zend_internal_arg_info,

Zend/zend_language_parser.y

@@ -817,13 +817,13 @@ optional_cpp_modifiers:
 
 parameter:
 		optional_cpp_modifiers optional_type_without_static
-		is_reference is_variadic T_VARIABLE backup_doc_comment optional_property_hook_list
+		is_reference is_variadic T_VARIABLE optional_property_hook_list backup_doc_comment
 			{ $$ = zend_ast_create_ex(ZEND_AST_PARAM, $1 | $3 | $4, $2, $5, NULL,
-					NULL, $6 ? zend_ast_create_zval_from_str($6) : NULL, $7); }
+					NULL, $7 ? zend_ast_create_zval_from_str($7) : NULL, $6); }
 	|	optional_cpp_modifiers optional_type_without_static
-		is_reference is_variadic T_VARIABLE backup_doc_comment '=' expr optional_property_hook_list
-			{ $$ = zend_ast_create_ex(ZEND_AST_PARAM, $1 | $3 | $4, $2, $5, $8,
-					NULL, $6 ? zend_ast_create_zval_from_str($6) : NULL, $9); }
+		is_reference is_variadic T_VARIABLE '=' expr optional_property_hook_list backup_doc_comment
+			{ $$ = zend_ast_create_ex(ZEND_AST_PARAM, $1 | $3 | $4, $2, $5, $7,
+					NULL, $9 ? zend_ast_create_zval_from_str($9) : NULL, $8); }
 ;
 
 optional_type_without_static:

Zend/zend_opcode.c

@@ -648,6 +648,9 @@ ZEND_API void destroy_op_array(zend_op_array *op_array)
 			if (arg_info[i].name) {
 				zend_string_release_ex(arg_info[i].name, 0);
 			}
+			if (arg_info[i].doc_comment) {
+				zend_string_release_ex(arg_info[i].doc_comment, 0);
+			}
 			zend_type_release(arg_info[i].type, /* persistent */ false);
 		}
 		efree(arg_info);

ext/reflection/php_reflection.c

@@ -2653,6 +2653,21 @@ ZEND_METHOD(ReflectionParameter, __toString)
 
 /* }}} */
 
+/* {{{ Returns the doc comment for this function */
+ZEND_METHOD(ReflectionParameter, getDocComment)
+{
+	reflection_object *intern;
+	parameter_reference *param;
+
+	ZEND_PARSE_PARAMETERS_NONE();
+
+	GET_REFLECTION_OBJECT_PTR(param);
+	if (param->arg_info->doc_comment) {
+		RETURN_STR_COPY(param->arg_info->doc_comment);
+	}
+	RETURN_FALSE;
+}
+
 /* {{{ Returns this parameter's name */
 ZEND_METHOD(ReflectionParameter, getName)
 {

ext/reflection/php_reflection.stub.php

@@ -648,6 +648,9 @@ public function __construct($function, int|string $param) {}
 
     public function __toString(): string {}
 
+    /** @tentative-return-type */
+    public function getDocComment(): string|false {}
+
     /** @tentative-return-type */
     public function getName(): string {}
 

ext/reflection/php_reflection_arginfo.h

@@ -0,0 +1,72 @@
+--TEST--
+Test ReflectionParameter::getDocComment() usage.
+--INI--
+opcache.save_comments=1
+--FILE--
+<?php
+
+function func(
+    /**
+     * My Doc Comment for $a
+     *
+     */
+    $a, $b, $c,
+    /**
+     * My Doc Comment for $d
+     */
+    $d,
+    /**Not a doc comment */
+    $e,
+    /**
+     * Doc comment for $f
+     */
+    $f,
+	$g /** Doc comment for $g behind parameter */,
+) {}
+
+foreach(['func'] as $function) {
+    $rc = new ReflectionFunction($function);
+    $rps = $rc->getParameters();
+    foreach($rps as $rp) {
+        echo "\n\n---> Doc comment for $function $" . $rp->getName() . ":\n";
+        var_dump($rp->getDocComment());
+    }
+}
+
+?>
+--EXPECTF--
+---> Doc comment for func $a:
+string(%d) "/**
+     * My Doc Comment for $a
+     *
+     */"
+
+
+---> Doc comment for func $b:
+bool(false)
+
+
+---> Doc comment for func $c:
+bool(false)
+
+
+---> Doc comment for func $d:
+string(%d) "/**
+     * My Doc Comment for $d
+     */"
+
+
+---> Doc comment for func $e:
+bool(false)
+
+
+---> Doc comment for func $f:
+string(%d) "/**
+     * Doc comment for $f
+     */"
+
+
+---> Doc comment for func $g:
+string(%d) "/** Doc comment for $g behind parameter */"
+
+