Skip to content

Implement "support doc comments for internal classes and functions" #13266

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Feb 25, 2024
Merged

Implement "support doc comments for internal classes and functions" #13266

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
411b152
Implement "support doc comments for internal classes and functions"
kocsismate Jan 29, 2024
6a2247e
Test fixes
kocsismate Jan 30, 2024
110b8dc
Fix another bunch of tests
kocsismate Feb 3, 2024
be521b5
Address review comments
kocsismate Feb 12, 2024
6d68bda
Do not generate frameless function entries for PHP 8.4<
kocsismate Feb 18, 2024
627d8e9
Fix space indentation
kocsismate Feb 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion Zend/zend.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -219,12 +219,13 @@ struct _zend_class_entry {
uint32_t enum_backing_type;
HashTable *backed_enum_table;

zend_string *doc_comment;

union {
struct {
zend_string *filename;
uint32_t line_start;
uint32_t line_end;
zend_string *doc_comment;
} user;
struct {
const struct _zend_function_entry *builtin_functions;
Expand Down
1 change: 1 addition & 0 deletions Zend/zend_API.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2859,6 +2859,7 @@ ZEND_API zend_result zend_register_functions(zend_class_entry *scope, const zend
while (ptr->fname) {
fname_len = strlen(ptr->fname);
internal_function->handler = ptr->handler;
internal_function->doc_comment = ptr->doc_comment ? zend_string_init_interned(ptr->doc_comment, strlen(ptr->doc_comment), 1) : NULL;
internal_function->function_name = zend_string_init_interned(ptr->fname, fname_len, 1);
internal_function->scope = scope;
internal_function->prototype = NULL;
Expand Down
45 changes: 23 additions & 22 deletions Zend/zend_API.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ typedef struct _zend_function_entry {
uint32_t num_args;
uint32_t flags;
const zend_frameless_function_info *frameless_function_infos;
const char *doc_comment;
} zend_function_entry;

typedef struct _zend_fcall_info {
Expand Down Expand Up @@ -74,31 +75,31 @@ typedef struct _zend_fcall_info_cache {
#define ZEND_FUNCTION(name) ZEND_NAMED_FUNCTION(zif_##name)
#define ZEND_METHOD(classname, name) ZEND_NAMED_FUNCTION(zim_##classname##_##name)

#define ZEND_FENTRY(zend_name, name, arg_info, flags) { #zend_name, name, arg_info, (uint32_t) (sizeof(arg_info)/sizeof(struct _zend_internal_arg_info)-1), flags, NULL },
#define ZEND_FENTRY(zend_name, name, arg_info, flags) { #zend_name, name, arg_info, (uint32_t) (sizeof(arg_info)/sizeof(struct _zend_internal_arg_info)-1), flags, NULL, NULL },

#define ZEND_RAW_FENTRY(zend_name, name, arg_info, flags, frameless_function_infos) { zend_name, name, arg_info, (uint32_t) (sizeof(arg_info)/sizeof(struct _zend_internal_arg_info)-1), flags, frameless_function_infos },
#define ZEND_RAW_FENTRY(zend_name, name, arg_info, flags, frameless_function_infos, doc_comment) { zend_name, name, arg_info, (uint32_t) (sizeof(arg_info)/sizeof(struct _zend_internal_arg_info)-1), flags, frameless_function_infos, doc_comment },

/* Same as ZEND_NAMED_FE */
#define ZEND_RAW_NAMED_FE(zend_name, name, arg_info) ZEND_RAW_FENTRY(#zend_name, name, arg_info, 0, NULL)
#define ZEND_RAW_NAMED_FE(zend_name, name, arg_info) ZEND_RAW_FENTRY(#zend_name, name, arg_info, 0, NULL, NULL)

#define ZEND_NAMED_FE(zend_name, name, arg_info) ZEND_RAW_FENTRY(#zend_name, name, arg_info, 0, NULL)
#define ZEND_FE(name, arg_info) ZEND_RAW_FENTRY(#name, zif_##name, arg_info, 0, NULL)
#define ZEND_DEP_FE(name, arg_info) ZEND_RAW_FENTRY(#name, zif_##name, arg_info, ZEND_ACC_DEPRECATED, NULL)
#define ZEND_FALIAS(name, alias, arg_info) ZEND_RAW_FENTRY(#name, zif_##alias, arg_info, 0, NULL)
#define ZEND_DEP_FALIAS(name, alias, arg_info) ZEND_RAW_FENTRY(#name, zif_##alias, arg_info, ZEND_ACC_DEPRECATED, NULL)
#define ZEND_NAMED_FE(zend_name, name, arg_info) ZEND_RAW_FENTRY(#zend_name, name, arg_info, 0, NULL, NULL)
#define ZEND_FE(name, arg_info) ZEND_RAW_FENTRY(#name, zif_##name, arg_info, 0, NULL, NULL)
#define ZEND_DEP_FE(name, arg_info) ZEND_RAW_FENTRY(#name, zif_##name, arg_info, ZEND_ACC_DEPRECATED, NULL, NULL)
#define ZEND_FALIAS(name, alias, arg_info) ZEND_RAW_FENTRY(#name, zif_##alias, arg_info, 0, NULL, NULL)
#define ZEND_DEP_FALIAS(name, alias, arg_info) ZEND_RAW_FENTRY(#name, zif_##alias, arg_info, ZEND_ACC_DEPRECATED, NULL, NULL)
#define ZEND_NAMED_ME(zend_name, name, arg_info, flags) ZEND_FENTRY(zend_name, name, arg_info, flags)
#define ZEND_ME(classname, name, arg_info, flags) ZEND_RAW_FENTRY(#name, zim_##classname##_##name, arg_info, flags, NULL)
#define ZEND_DEP_ME(classname, name, arg_info, flags) ZEND_RAW_FENTRY(#name, zim_##classname##_##name, arg_info, flags | ZEND_ACC_DEPRECATED, NULL)
#define ZEND_ABSTRACT_ME(classname, name, arg_info) ZEND_RAW_FENTRY(#name, NULL, arg_info, ZEND_ACC_PUBLIC|ZEND_ACC_ABSTRACT, NULL)
#define ZEND_ABSTRACT_ME_WITH_FLAGS(classname, name, arg_info, flags) ZEND_RAW_FENTRY(#name, NULL, arg_info, flags, NULL)
#define ZEND_MALIAS(classname, name, alias, arg_info, flags) ZEND_RAW_FENTRY(#name, zim_##classname##_##alias, arg_info, flags, NULL)
#define ZEND_ME_MAPPING(name, func_name, arg_info, flags) ZEND_RAW_FENTRY(#name, zif_##func_name, arg_info, flags, NULL)
#define ZEND_FRAMELESS_FE(name, arg_info, flags, frameless_function_infos) \
{ #name, zif_##name, arg_info, (uint32_t) (sizeof(arg_info)/sizeof(struct _zend_internal_arg_info)-1), flags, frameless_function_infos },

#define ZEND_NS_FENTRY(ns, zend_name, name, arg_info, flags) ZEND_RAW_FENTRY(ZEND_NS_NAME(ns, #zend_name), name, arg_info, flags, NULL)

#define ZEND_NS_RAW_FENTRY(ns, zend_name, name, arg_info, flags) ZEND_RAW_FENTRY(ZEND_NS_NAME(ns, zend_name), name, arg_info, flags, NULL)
#define ZEND_ME(classname, name, arg_info, flags) ZEND_RAW_FENTRY(#name, zim_##classname##_##name, arg_info, flags, NULL, NULL)
#define ZEND_DEP_ME(classname, name, arg_info, flags) ZEND_RAW_FENTRY(#name, zim_##classname##_##name, arg_info, flags | ZEND_ACC_DEPRECATED, NULL, NULL)
#define ZEND_ABSTRACT_ME(classname, name, arg_info) ZEND_RAW_FENTRY(#name, NULL, arg_info, ZEND_ACC_PUBLIC|ZEND_ACC_ABSTRACT, NULL, NULL)
#define ZEND_ABSTRACT_ME_WITH_FLAGS(classname, name, arg_info, flags) ZEND_RAW_FENTRY(#name, NULL, arg_info, flags, NULL, NULL)
#define ZEND_MALIAS(classname, name, alias, arg_info, flags) ZEND_RAW_FENTRY(#name, zim_##classname##_##alias, arg_info, flags, NULL, NULL)
#define ZEND_ME_MAPPING(name, func_name, arg_info, flags) ZEND_RAW_FENTRY(#name, zif_##func_name, arg_info, flags, NULL, NULL)
#define ZEND_FRAMELESS_FE(name, arg_info, flags, frameless_function_infos, doc_comment) \
{ #name, zif_##name, arg_info, (uint32_t) (sizeof(arg_info)/sizeof(struct _zend_internal_arg_info)-1), flags, frameless_function_infos, doc_comment },

#define ZEND_NS_FENTRY(ns, zend_name, name, arg_info, flags) ZEND_RAW_FENTRY(ZEND_NS_NAME(ns, #zend_name), name, arg_info, flags, NULL, NULL)

#define ZEND_NS_RAW_FENTRY(ns, zend_name, name, arg_info, flags) ZEND_RAW_FENTRY(ZEND_NS_NAME(ns, zend_name), name, arg_info, flags, NULL, NULL)
/**
* Note that if you are asserting that a function is compile-time evaluable, you are asserting that
*
Expand All @@ -109,7 +110,7 @@ typedef struct _zend_fcall_info_cache {
* 4. The function will not take an unreasonable amount of time or memory to compute on code that may be seen in practice.
* (e.g. str_repeat is special cased to check the length instead of using this)
*/
#define ZEND_SUPPORTS_COMPILE_TIME_EVAL_FE(name, arg_info) ZEND_RAW_FENTRY(#name, zif_##name, arg_info, ZEND_ACC_COMPILE_TIME_EVAL, NULL)
#define ZEND_SUPPORTS_COMPILE_TIME_EVAL_FE(name, arg_info) ZEND_RAW_FENTRY(#name, zif_##name, arg_info, ZEND_ACC_COMPILE_TIME_EVAL, NULL, NULL)

/* Same as ZEND_NS_NAMED_FE */
#define ZEND_NS_RAW_NAMED_FE(ns, zend_name, name, arg_info) ZEND_NS_RAW_FENTRY(ns, #zend_name, name, arg_info, 0)
Expand All @@ -120,7 +121,7 @@ typedef struct _zend_fcall_info_cache {
#define ZEND_NS_FALIAS(ns, name, alias, arg_info) ZEND_NS_RAW_FENTRY(ns, #name, zif_##alias, arg_info, 0)
#define ZEND_NS_DEP_FALIAS(ns, name, alias, arg_info) ZEND_NS_RAW_FENTRY(ns, #name, zif_##alias, arg_info, ZEND_ACC_DEPRECATED)

#define ZEND_FE_END { NULL, NULL, NULL, 0, 0, NULL }
#define ZEND_FE_END { NULL, NULL, NULL, 0, 0, NULL, NULL }

#define _ZEND_ARG_INFO_FLAGS(pass_by_ref, is_variadic, is_tentative) \
(((pass_by_ref) << _ZEND_SEND_MODE_SHIFT) | ((is_variadic) ? _ZEND_IS_VARIADIC_BIT : 0) | ((is_tentative) ? _ZEND_IS_TENTATIVE_BIT : 0))
Expand Down
16 changes: 8 additions & 8 deletions Zend/zend_builtin_functions_arginfo.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions Zend/zend_closures.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -365,6 +365,7 @@ static zend_result zend_create_closure_from_callable(zval *return_value, zval *c
call.handler = zend_closure_call_magic;
call.function_name = mptr->common.function_name;
call.scope = mptr->common.scope;
call.doc_comment = NULL;

zend_free_trampoline(mptr);
mptr = (zend_function *) &call;
Expand Down Expand Up @@ -479,6 +480,7 @@ ZEND_API zend_function *zend_get_closure_invoke_method(zend_object *object) /* {
ZEND_ACC_USER_ARG_INFO;
}
invoke->internal_function.handler = ZEND_MN(Closure___invoke);
invoke->internal_function.doc_comment = NULL;
invoke->internal_function.module = 0;
invoke->internal_function.scope = zend_ce_closure;
invoke->internal_function.function_name = ZSTR_KNOWN(ZEND_STR_MAGIC_INVOKE);
Expand Down Expand Up @@ -864,6 +866,7 @@ void zend_closure_from_frame(zval *return_value, zend_execute_data *call) { /* {
trampoline.handler = zend_closure_call_magic;
trampoline.function_name = mptr->common.function_name;
trampoline.scope = mptr->common.scope;
trampoline.doc_comment = NULL;
if (trampoline.fn_flags & ZEND_ACC_VARIADIC) {
trampoline.arg_info = trampoline_arg_info;
}
Expand Down
7 changes: 3 additions & 4 deletions Zend/zend_compile.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2001,9 +2001,8 @@ ZEND_API void zend_initialize_class_data(zend_class_entry *ce, bool nullify_hand
zend_hash_init(&ce->constants_table, 8, NULL, NULL, persistent_hashes);
zend_hash_init(&ce->function_table, 8, NULL, ZEND_FUNCTION_DTOR, persistent_hashes);

if (ce->type == ZEND_USER_CLASS) {
ce->info.user.doc_comment = NULL;
}
ce->doc_comment = NULL;

ZEND_MAP_PTR_INIT(ce->static_members_table, NULL);
ZEND_MAP_PTR_INIT(ce->mutable_data, NULL);

Expand Down Expand Up @@ -8278,7 +8277,7 @@ static void zend_compile_class_decl(znode *result, zend_ast *ast, bool toplevel)
ce->info.user.line_end = decl->end_lineno;

if (decl->doc_comment) {
ce->info.user.doc_comment = zend_string_copy(decl->doc_comment);
ce->doc_comment = zend_string_copy(decl->doc_comment);
}

if (UNEXPECTED((decl->flags & ZEND_ACC_ANON_CLASS))) {
Expand Down
4 changes: 3 additions & 1 deletion Zend/zend_compile.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -464,6 +464,7 @@ struct _zend_op_array {
zend_arg_info *arg_info;
HashTable *attributes;
ZEND_MAP_PTR_DEF(void **, run_time_cache);
zend_string *doc_comment;
uint32_t T; /* number of temporary variables */
/* END of common elements */

Expand All @@ -486,7 +487,6 @@ struct _zend_op_array {
zend_string *filename;
uint32_t line_start;
uint32_t line_end;
zend_string *doc_comment;

int last_literal;
uint32_t num_dynamic_func_defs;
Expand Down Expand Up @@ -522,6 +522,7 @@ typedef struct _zend_internal_function {
zend_internal_arg_info *arg_info;
HashTable *attributes;
ZEND_MAP_PTR_DEF(void **, run_time_cache);
zend_string *doc_comment;
uint32_t T; /* number of temporary variables */
/* END of common elements */

Expand Down Expand Up @@ -549,6 +550,7 @@ union _zend_function {
zend_arg_info *arg_info; /* index -1 represents the return value info, if any */
HashTable *attributes;
ZEND_MAP_PTR_DEF(void **, run_time_cache);
zend_string *doc_comment;
uint32_t T; /* number of temporary variables */
} common;

Expand Down
3 changes: 3 additions & 0 deletions Zend/zend_enum.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -437,6 +437,7 @@ void zend_enum_register_funcs(zend_class_entry *ce)
cases_function->handler = zend_enum_cases_func;
cases_function->function_name = ZSTR_KNOWN(ZEND_STR_CASES);
cases_function->fn_flags = fn_flags;
cases_function->doc_comment = NULL;
cases_function->arg_info = (zend_internal_arg_info *) (arginfo_class_UnitEnum_cases + 1);
zend_enum_register_func(ce, ZEND_STR_CASES, cases_function);

Expand All @@ -445,6 +446,7 @@ void zend_enum_register_funcs(zend_class_entry *ce)
from_function->handler = zend_enum_from_func;
from_function->function_name = ZSTR_KNOWN(ZEND_STR_FROM);
from_function->fn_flags = fn_flags;
from_function->doc_comment = NULL;
from_function->num_args = 1;
from_function->required_num_args = 1;
from_function->arg_info = (zend_internal_arg_info *) (arginfo_class_BackedEnum_from + 1);
Expand All @@ -454,6 +456,7 @@ void zend_enum_register_funcs(zend_class_entry *ce)
try_from_function->handler = zend_enum_try_from_func;
try_from_function->function_name = ZSTR_KNOWN(ZEND_STR_TRYFROM);
try_from_function->fn_flags = fn_flags;
try_from_function->doc_comment = NULL;
try_from_function->num_args = 1;
try_from_function->required_num_args = 1;
try_from_function->arg_info = (zend_internal_arg_info *) (arginfo_class_BackedEnum_tryFrom + 1);
Expand Down
6 changes: 3 additions & 3 deletions Zend/zend_enum_arginfo.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

36 changes: 18 additions & 18 deletions Zend/zend_exceptions_arginfo.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading