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 ?

Fixes #60646 (Trac)

### Summary
Updates the get_post_custom() docblock in src/wp-includes/post.php to remove the incorrect claim that negative post IDs are invalid. Negative IDs are normalized via absint() in the function, so they should not be documented as invalid.

### Changes

• Docblock only (no functional code changes)

### Tested

• Docs-only change (no runtime behavior affected)

You do not need to merge the latest changes from trunk, unless there is a merge conflict or likely to be a change in trunk which would impact this branch. If you see "Update Branch" feel free to leave it as-is, as otherwise it just spins up a lot of jobs which aren't going to be doing any meaningful work.

[westonruter]

In 61718:

Docs: Improve accuracy of @return type and description for get_post_custom().

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10996

Follow-up to [52795].

Props ravikhadka, westonruter, swissspidy, roytanck.
See #64224, #55249.
Fixes #60646.