PHPDoc errors in functions.php

[subrataemfluence]

File: wp-includes/functions.php

Issues:

PHPDoc: non-existing argument (line nos. 775, 776, 777)
PHPDoc: Unhandled Exception (line no. 3082)
PHPDoc: Argument type mismatch (line no. 3542)

[subrataemfluence]

Proposed patch

[subrataemfluence]

Also there are some areas where unused parameters are reported.
Is this a good idea to get rid of those?

Example: $title parameter is not used anywhere in the function

function _xmlrpc_wp_die_handler( $message, $title = '', $args = array() ) { ... }

[SergeyBiryukov]

Thanks for the patch!

add_query_arg() arguments are correct, it uses func_get_args() to get them. The rest looks good.

In _xmlrpc_wp_die_handler(), even though the $title argument is not used, we cannot remove it. The function signature needs to remain consistent with _default_wp_die_handler() and _ajax_wp_die_handler().

[subrataemfluence]

Replying to SergeyBiryukov:

add_query_arg() arguments are correct, it uses func_get_args() to get them

In this case, I think it might be more logical to mention how it actually gets the arguments. To me it looks a bit misleading to have them here without mentioning the actual source. May be not super important, but might be given a thought! :)

In _xmlrpc_wp_die_handler(), even though the $title argument is not used, we cannot remove it. The function signature needs to remain consistent with _default_wp_die_handler() and _ajax_wp_die_handler().

Understood!

[johnbillion]

Partially related: #37402

[johnbillion]

Replying to subrataemfluence:

In this case, I think it might be more logical to mention how it actually gets the arguments. To me it looks a bit misleading to have them here without mentioning the actual source. May be not super important, but might be given a thought! :)

The function's usage is documented in the docblock summary, but granted it's not clear how its parameters are populated just by looking at the docs. Suggestions for improvements to the summary or its parameter docs welcome.

[audrasjb]

As per today's bug scrub, we are going to move this one to Future Release since beta 3 and RC are approaching.

[SergeyBiryukov]

Replying to johnbillion:

The function's usage is documented in the docblock summary, but granted it's not clear how its parameters are populated just by looking at the docs. Suggestions for improvements to the summary or its parameter docs welcome.

This part appears to be resolved in [46126] / #47678, the function signature now includes the spread operator.

[SergeyBiryukov]

In 47427:

Docs: Add missing @throws tag to _wp_json_sanity_check() DocBlock.

Props subrataemfluence.
See #45643.

[SergeyBiryukov]

In 47429:

General: Correct the default value of the $defaults parameter in wp_parse_args() to match the documented type.

Props subrataemfluence.
See #45643.

[SergeyBiryukov]

In 47430:

General: Ensure get_tag_regex() always returns a string, to match the documented value.

Props subrataemfluence.
Fixes #45643.

[SergeyBiryukov]

#44453 was marked as a duplicate.