PHPDoc for embed_handler_html is misleading

[apermo]

<?php
( false !== $return ) {
        /**
         * Filters the returned embed HTML.
         *
         * @since 2.9.0
         *
         * @see WP_Embed::shortcode()
         *
         * @param string|false $return The HTML result of the shortcode, or false on failure.
         * @param string       $url    The embed URL.
         * @param array        $attr   An array of shortcode attributes.
         */
        return apply_filters( 'embed_handler_html', $return, $url, $attr );
}

Similar argument as in #63220, but even easier.

While the documentation suggests that $return can be false or a string, it can't be false, we are testing exactly for that.

This is misleading.

I've checked the whole file's filters this time, all others look good to me, no actions in that file.

PR follows.

docs: Fixed parameter type and descriptions for embed_handler_html filter.

Trac ticket: https://core.trac.wordpress.org/ticket/63248#ticket

Note for reviewers: Hit expand to top once.

You'll see that there is a condition right before the PHPDoc saying false !== $return

[SergeyBiryukov]

In 60149:

Docs: Correct the type of the $return parameter in embed_handler_html filter.

The value cannot be false at this point, as the filter is only applied to non-empty embed HTML.

Follow-up to [25726], [46661].

Props apermo, jasonsa19.
Fixes #63248.

[SergeyBiryukov]

Thanks for the ticket! Reopening for 6.8.x consideration to complement [60140] / #63220.

[audrasjb]

Marking as ready for 6.8 backport as #63220 was backported last week.

[audrasjb]

Self assigning for backport.

[audrasjb]

In 60157:

Docs: Correct the type of the $return parameter in embed_handler_html filter.

The value cannot be false at this point, as the filter is only applied to non-empty embed HTML.

Follow-up to [25726], [46661].

Reviewed by SergeyBiryukov, audrasjb.
Merges [60149] to 6.8 branch.
Props apermo, jasonsa19.
Fixes #63248.