Docblock improvements for WP 6.7

[hellofromTonya]

Previously:

• #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)

I found that the sentence in this doc flows weird... It's as if there is a verb missing.

Trac ticket:
https://core.trac.wordpress.org/ticket/61608
https://core.trac.wordpress.org/ticket/58833

[SergeyBiryukov]

In 58842:

Docs: Improve the wording for cron_reschedule_event_error action description.

Follow-up to [54258].

Props NekoJonez, audrasjb.
See #61608.

Thanks for the PR! Merged in r58842.

According to Inline Documentation Standards, just removed extra space from the comment.

• Inline Documentation Standards: ​https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/

[SergeyBiryukov]

In 58865:

Docs: Correct alignment for rest_insert_attachment action DocBlock.

Follow-up to [39348].

Props krupalpanchal.
See #61608.

Thanks for the PR! Merged in r58865.

[SergeyBiryukov]

In 58883:

Docs: Switch canonical location for the comment_row_actions filter.

This aims to bring consistency with the other *_row_actions filters.

Follow-up to [6705], [8217], [9103], [15491], [26138], [27669].

See #61608.

[SergeyBiryukov]

In 58924:

Docs: Correct inline comment formatting in redirect_canonical().

Follow-up to [57357].

See #61608.

The return value documentation for the get_*_meta() and get_metadata() functions incorrectly stated that an empty string is returned if a valid but non-existing object ID is passed. Actually, an empty string is returned if a valid but non-existing object ID is passed and $single is true. Otherwise, an empty array is returned.

This PR fixes the return value documentation for those functions.

It also includes some very basic tests documenting this behavior for get_metadata(). Happy to add similar tests for the other functions if needed.

The documentation that is modified by this PR was added in https://core.trac.wordpress.org/changeset/50641.

[SergeyBiryukov]

In 58948:

Docs: Remove obsolete @todo entry in REST API post meta tests.

Follow-up to [56714].

See #61608.

[rodrigosprimo]

Noting here that I created ​https://github.com/WordPress/wordpress-develop/pull/7259 to fix the return value documentation for get_*_meta() functions.

[SergeyBiryukov]

In 58955:

Docs: Clarify the description for wp_dropdown_users().

Follow-up to [8873].

See #61608.

[SergeyBiryukov]

In 58961:

Docs: Correct comment formatting in wp_autosave_post_revisioned_meta_fields().

Follow-up to [56714].

See #61608.

[SergeyBiryukov]

In 58962:

Docs: Further clarify return results for a non-existing ID in metadata functions.

This adds a note that the functions return either an empty array or an empty string for a valid but non-existing ID, depending on the $single parameter.

Follow-up to [48658], [50641].

Props rodrigosprimo, jrf.
See #61608.

[SergeyBiryukov]

In 58968:

Tests: Add a unit test for get_metadata() with a non-existing object ID.

Follow-up to [48658], [50641], [58962].

Props rodrigosprimo, jrf.
See #61530, #61608.

Thanks for the PR! Merged in r58962 and r58968.

Thanks @SergeyBiryukov!

[SergeyBiryukov]

In 58993:

Docs: Correct the first parameter name for the pre_site_option_{$option} filter.

Follow-up to [27365], [41013], [48193].

See #61608.

[johnbillion]

In 59009:

Docs: Various docblock improvements and corrections.

See #61608

https://core.trac.wordpress.org/changeset/59009

[SergeyBiryukov]

In 59010:

Docs: Remove the @ignore tag for _wp_render_title_tag().

The function is referenced in the _block_template_render_title_tag() DocBlock, and should therefore be included in the documentation.

Follow-up to [30074], [30615], [31170], [35294], [51003].

Props poena.
See #61608.

[SergeyBiryukov]

In 59017:

Tests: Restore the environment before performing assertions in some canonical tests.

This aims to avoid affecting other tests in case of failure.

Follow-up to [28704], [45133].

See #61608.

[SergeyBiryukov]

In 59125:

Docs: Add a @since note to map_meta_cap() for edit_block_binding capability.

Follow-up to [59122].

See #61608.

[SergeyBiryukov]

In 59165:

Docs: Use typed array notation for the $attrs parameter in links_add_base_url().

Follow-up to [8540], [32590], [46596].

See #61608.

[peterwilsoncc]

In 59193:

Docs/Bundled Themes: Add @since annotation for introduction of TT5.

See #62180, #61608.

[SergeyBiryukov]

In 59196:

Docs: Synchronize description for the $instance parameter in WP_Widget methods.

Follow-up to [30382].

See #61608.

[johnbillion]

In 59203:

REST API: Correct the opening tag for this method's docblock.

Props szepeviktor

See #61608

[SergeyBiryukov]

In 59258:

Docs: Fix typo in a comment in WP_Rewrite::refresh_rewrite_rules().

Includes adjusting the method DocBlock per the documentation standards.

Follow-up to [56448].

See #61608.

[desrosj]

With RC1 due out in a few hours, I'm going to close this one out. If further updates are required, we can reopen this for them.

I've opened #62281 for 6.8.