Docs: Enhance inline documentation for current_time, wp_date, and date_i18n functions/filters.

[dilipbheda]

• The $gmt argument in the current_time function accepts a boolean value true|false
• The $timestamp and $timezone arguments in the wp_date function accept null, but this is not documented inline.
• The date_i18n filter documentation includes "Default false," but it seems unnecessary. Ref: ​https://tinyurl.com/236y7b5u

[SergeyBiryukov]

In 60119:

Docs: Correct documentation for current_time(), date_i18n(), and wp_date().

Includes:

• Standardizing on the bool type for the $gmt parameter between current_time() and date_i18n().
• Documenting null as an acceptable value for $timestamp and $timezone parameters in wp_date().
• Removing a redundant note on the $gmt parameter for the date_i18n filter, as defaults are normally only documented for function parameters.

Follow-up to [1001], [9616], [28109], [45901].

Props dilipbheda.
Fixes #63207.

[johnbillion]

[60119] is more than just a docs change, and there are unit tests that pass a non-boolean value to this function (test_orderby_date_modified_gmt_should_order_by_comment_ID_in_case_of_tie_ASC(), test_orderby_date_modified_gmt_should_order_by_comment_ID_in_case_of_tie_DESC(), maybe others) that should be updated. Functionally it's fine because that parameter is really a boolean, but let's be careful about calling something a docs change when it's technically more than that.

[dilipbheda]

@johnbillion Thanks for pointing this out! I checked and found that the core also uses the 1|0 value in some places, so it's possible that other plugins/themes use it as well.

You can check this here: ​https://github.com/search?q=repo%3AWordPress%2Fwordpress-develop+current_time%28+%27mysql%27%2C+&type=code

From my perspective, we should revert the @param type from bool to int|bool

What do you think?

cc @SergeyBiryukov

[SergeyBiryukov]

Replying to dilipbheda:

From my perspective, we should revert the @param type from bool to int|bool

What do you think?

I think bool is fine here, and is more consistent with the same parameter in date_i18n(). Let's update the instances in core and unit tests to pass true instead of 1 for consistency. It's OK if some plugins or themes would still pass 1, as the function just checks for a truthy value.

[SergeyBiryukov]

Replying to johnbillion:

Functionally it's fine because that parameter is really a boolean, but let's be careful about calling something a docs change when it's technically more than that.

Good point, thanks!

[dilipbheda]

@SergeyBiryukov I’ve applied your suggestion and opened a new PR.