Docs: Incorrect return type specified for get_post_custom with negative post ID value

[roytanck]

On the documentation page for get_post_custom, the return type section says:

"False for an invalid $post_id (non-numeric, zero, or negative value)."

​https://developer.wordpress.org/reference/functions/get_post_custom/

However, the function applies absint to the $post_id. So if its value would be negative (i.e. -10), this would be converted a positive value (10), and get_post_meta would be called for that post. This post ID can then either exists (resulting in an array being returned) or not (empty string).

Perhaps a negative numerical value should not converted? There's a potential for mix-ups? If we keep the code as is, the docs should probably specify that negative values are converted to positive.

[swissspidy]

The incorrect docs were added in [52795] / #55249

It was added because the underlying get_post_meta and get_metadata_raw functions have the same note about negative values. Introduced in [50641] / #51797. Thus setting the version here to 5.8.

So the problem is a bit more widespread and the docblock needs to be updated for more functions than just get_post_custom. There are about 8 occurrences of "(non-numeric, zero, or negative value)" in core at the moment .

Trac ticket: https://core.trac.wordpress.org/ticket/60646

• Docblock of functions get_post_meta() and get_post_custom() edited to correspond to negative value of the parameter $post_id
• Default value added in docblock of get_post_custom() for parameter $post_id

[getsyash]

Can i pickup this task ?