Documented @return for get_post_thumbnail_id() is inaccurate

[theMikeD]

Ticket #40096 introduced a new change to the return value of get_post_thumbnail_id() to now always return an int rather than an empty string if the post is valid. The function documentation is now inaccurate because the @return statement was not updated correctly. In turn, this means the official API documentation is now also inaccurate.

It currently says

@return int|string Post thumbnail ID or empty string if the post does not exist.

It should read

@return int|string Post thumbnail ID if found, 0 if the thumbnail image is not set, or empty string if the post does not exist.

[SergeyBiryukov]

Thanks for the ticket!

Just noting that this currently depends on the outcome of #49751, there's a possibility that [47160] might be reverted.

[dingo_d]

If someone will be patching this, be sure to add the @since tag in the docs so that we know when the change was made :)

[netpassprodsr]

The outcome of #49751 as of 4/9/2020 is the following:

Milestone 5.4.1 deleted
Resolution set to invalid
Status changed from new to closed

which leaves the [47160] in limbo.
I agree with the logic that this code change attempts to address.
That said, until there's a formal endorsement that this code change will be remain in place, modifying the docs to fit a "volatile" code change is unwise at this point.
My recommendation is to resolve this as "maybelater" unless a more appropriate workflow/handling of these cases should be followed.

[theMikeD]

I don't think leaving the docs in a known bad state is the right answer here. If the underlying change gets reverted, then the doc can be reverted along with it. But waiting for a resolution is a recipe for it being knowingly wrong.

get_post_thumbnail_id return value doc amendment

This correction to the php_doc brings the notes in line with the actual range of return values of the function.

Props theMikeD.
Fixes #49832.

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

<!--
Hi there! Thanks for contributing to WordPress!

Pull Requests in this GitHub repository must be linked to a ticket in the WordPress Core Trac instance (​https://core.trac.wordpress.org), and are only used for code review. No pull requests will be merged on GitHub.

See the WordPress Handbook page on using PRs for Code Review more information: ​https://make.wordpress.org/core/handbook/contribute/git/github-pull-requests-for-code-review/

If this is your first time contributing, you may also find reviewing these guides first to be helpful:

• FAQs for New Contributors: ​https://make.wordpress.org/core/handbook/tutorials/faq-for-new-contributors/
• Contributing with Code Guide: ​https://make.wordpress.org/core/handbook/contribute/
• WordPress Coding Standards: ​https://make.wordpress.org/core/handbook/best-practices/coding-standards/
• Inline Documentation Standards: ​https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/
• Browser Support Policies: ​https://make.wordpress.org/core/handbook/best-practices/browser-support/
• Proper spelling and grammar related best practices: ​https://make.wordpress.org/core/handbook/best-practices/spelling/

-->

Trac ticket:

[SergeyBiryukov]

In 48310:

Post Thumbnails: Change the return value of get_post_thumbnail_id() for a non-existing post to false instead of an empty string.

This further makes the function more consistent with get_the_ID() or wp_get_post_parent_id(), both returning false for a non-existing post.

Additionally, document that get_post_thumbnail_id() returns 0 if the thumbnail image is not set.

Follow-up to [47160].

Props theMikeD, dingo_d, netpassprodsr, SergeyBiryukov.
Fixes #49832. See #40096.