Docblock improvements for WP 6.8

[desrosj]

Previously:

• #61608 (6.7)
• #60699 (6.6)
• #59651 (6.5)
• #58833 (6.4)
• #57840 (6.3)
• #56792 (6.2)
• #55646 (6.1)
• #54729 (6.0)
• #53399 (5.9)
• #52628 (5.8)
• #51800 (5.7)
• #50768 (5.6)
• #49572 (5.5)
• #48303 (5.4)
• #47110 (5.3)
• #46543 (5.2)
• #42505 (5.1)
• #41017 (4.9)
• #39130 (4.8)
• #37770 (4.7)
• #32246 (4.6)

[SergeyBiryukov]

In 59291:

Docs: Adjust comments about set_time_limit() per the documentation standards.

Includes splitting long comments into multiple lines and moving a few comments above the function_exists() check for more consistent placement.

Follow-up to [59039], [59288].

See #62281.

[SergeyBiryukov]

In 59333:

Docs: Correct @param tag in untrailingslashit() to match the parameter name.

Follow-up to [54927].

Props justlevine.
See #52217, #62281.

[SergeyBiryukov]

In 59334:

Docs: Correct @param type in fix_phpmailer_messageid().

Follow-up to [48033].

Props justlevine.
See #52217, #62281.

[SergeyBiryukov]

In 59336:

Docs: Add missing void to DocBlock @return types.

This commit adds missing void return types to (parent) methods that can explicitly return void as one of their conditional paths.

Addressed methods:

• WP_Privacy_Requests_Table::column_status()
• WP_Recovery_Mode::handle_error()
• WP_Widget::form() — unlike the others, it's the child classes that return void when the method is correctly implemented.

Note: @return void (where void is the single type returned) should not be used outside the default bundled themes and the PHP compatibility shims included in WordPress Core, as per the ​documentation standards.

Follow-up to [30382], [42967], [43256], [44973], [45448].

Props justlevine.
See #52217, #62281.

[johnbillion]

In 59405:

Docs: Correct the spelling of silicon in the local development environment readme.

See #62281

​The `script_module_data_{$module_id}` filter documentation is truncated.. It seems that the example tag is not processed and instead ends the description section of the documentation.

Change the examples for this filter to use Example: and an indented code block. This ​seems to work in other places:

​https://github.com/WordPress/wordpress-develop/blob/b6f639737c5fa722dd5a80f0ad94e48c67c37ffd/src/wp-includes/functions.php#L7514-L7525

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

[SergeyBiryukov]

In 59505:

Docs: Correct formatting for script module data filter documentation examples.

Follow-up to [58579].

Props jonsurrell.
See #62281.

Thanks for the PR! Merged in r59505.

[audrasjb]

In 59549:

Docs: Docblock improvements in .

Props shailu25.
Fixes #62730.
See #62281.

[audrasjb]

In 59702:

Docs: Various Docblock fixes in wp-includes/widgets.php, as per WP Docs standards;

Props ankitpatel1578, sabernhardt.
Fixes #62859.
See #62281.

[audrasjb]

In 59704:

Docs: Improve @return docblock section for get_category().

This changeset adds more details on the WP_Term returned by get_category() as it contains additional backwards compatible aliases for the era before WP 4.4 and 2.3.

Props apermo, audrasjb.
Fixes #62842.
See #62281.

[audrasjb]

In 59734:

Docs: Improve docblock for rest_menu_read_access filter.

Follow-up to [59718].

See #62281, #54304.

[SergeyBiryukov]

In 59756:

Docs: Correct DocBlock formatting for the_password_form filter.

Follow-up to [59736], [59737].

See #62281.

[audrasjb]

In 59785:

Docs: Various Docblock fixes in wp-includes/class-wp-customize-control.php, as per WP Docs standards;

See #62281.

[audrasjb]

In 59787:

Docs: Fix Docblock parameters indentation for wp_determine_option_autoload_value(), as per WP Docs standards.

See #62281.

[SergeyBiryukov]

In 59829:

Docs: Correct formatting for get_the_date and get_the_time DocBlocks.

Follow-up to [53000].

See #62281.

[SergeyBiryukov]

In 59836:

Docs: Correct the type for the_modified_date filter parameter.

Due to concatenation directly above, this value can only be a string.

Follow-up to [28130], [48929].

See #62281.

[johnbillion]

In 59861:

Docs: Various improvements to inline documentation.

See #62281

[SergeyBiryukov]

In 59864:

Docs: Correct DocBlock formatting for wp_check_comment_disallowed_list().

Follow-up to [6553], [48121], [48575].

See #62281.

[johnbillion]

In 59865:

Docs: Various improvements to inline documentation.

See #62281

[SergeyBiryukov]

In 59871:

Docs: Correct the type for transition_comment_status action parameters.

By the time this hook runs, the $new_status and $old_status values can only be a string.

Follow-up to [26491].

See #62281.

[SergeyBiryukov]

In 59882:

Docs: Correct the type for ::prepare_status_response() parameter in WP_REST_Comments_Controller.

The accepted value is WP_Comment::$comment_approved, which is documented as a string.

Follow-up to [38832], [33891], [39015], [59805], [59871].

See #62281.

[johnbillion]

In 59896:

Docs: Various improvements to inline documentation.

See #62281

[johnbillion]

In 59927:

Docs: Various improvements to inline documentation.

See #62281

[audrasjb]

In 59940:

Docs: Update $network_id parameter type to int|null in Network Option methods.

Props maikelraow, im3dabasia1, audrasjb, mukesh27.
Fixes #62735.
See #62281.

[SergeyBiryukov]

In 59952:

Docs: Clarify the backward compatibility reference in get_calendar() DocBlock.

Includes adjusting the @since note for the get_calendar filter, as the reference is only relevant for the function DocBlock.

Follow-up to [59908].

See #62281.

[SergeyBiryukov]

In 59979:

Docs: Correct formatting for some inline comments in unit tests.

Follow-up to [54111], [56714], [58182], [59630], [59817], [59966].

See #62281.

[desrosj]

I've gone and opened #63166 for 6.9. If any additional changes are required for 6.8, we can reopen this.