Skip to content

Hooks/Docs: Missing PHPDoc on deprecated hooks in wp-includes/deprecated.php and ms-deprecated.php (19 hooks) #26

Closed as not planned

Description

@apermo

Summary

19 hook calls in wp-includes/deprecated.php and wp-includes/ms-deprecated.php have no PHPDoc block. All are inside deprecated wrapper functions and most should use a /** This filter/action is documented in … */ cross-reference comment pointing to the current canonical location.


wp-includes/deprecated.php — Filters

the_title (×4) — used in deprecated get_the_title() / previous_post() / next_post() wrappers. Primary PHPDoc is in wp-includes/post-template.php.

https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/deprecated.php#L153
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/deprecated.php#L188
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/deprecated.php#L2705
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/deprecated.php#L2782

link_category (line 1063) — in deprecated get_links_list().

https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/deprecated.php#L1063

attachment_max_dims (line 1951), attachment_icon (line 1980), attachment_innerHTML (line 2006) — in deprecated get_attachment_innerHTML() / get_attachment_icon().

https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/deprecated.php#L1951
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/deprecated.php#L1980
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/deprecated.php#L2006

{$boundary}_post_rel_link (line 2712), index_rel_link (line 2743), parent_post_rel_link (line 2788) — in deprecated rel-link functions.

https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/deprecated.php#L2712
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/deprecated.php#L2743
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/deprecated.php#L2788

extra_theme_headers (line 3095) — in deprecated get_theme_data(). Primary PHPDoc likely in wp-includes/theme.php.

https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/deprecated.php#L3095


wp-includes/deprecated.php — Actions

delete_usermeta (line 2243), deleted_usermeta (line 2254), update_usermeta (line 2351), added_usermeta (line 2364), updated_usermeta (line 2366) — in deprecated update_usermeta() / delete_usermeta(). These hooks are deprecated themselves and have no modern equivalent. They need their own PHPDoc with @deprecated.

https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/deprecated.php#L2243
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/deprecated.php#L2254
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/deprecated.php#L2351
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/deprecated.php#L2364
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/deprecated.php#L2366


wp-includes/ms-deprecated.php — Filters

graceful_fail (line 91), graceful_fail_template (line 92) — in deprecated graceful_fail(). No modern equivalent; need their own PHPDoc with @deprecated.

https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/ms-deprecated.php#L91
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/ms-deprecated.php#L92


Fix approach

  • For hooks that have a current equivalent (e.g. the_title): replace bare calls with /** This filter is documented in wp-includes/post-template.php */.
  • For hooks that are deprecated themselves (usermeta hooks, graceful_fail, rel-link hooks): add a minimal PHPDoc with @since, @deprecated, and @param tags.

Activity

  1. added this to the Missing PHPDoc milestone on Mar 8, 2026
  2. apermo commented on Mar 8, 2026

    @apermo
    OwnerAuthor

    Cross-reference analysis

    Checked all hooks from this issue for multiple call sites:

    Need xref (canonical PHPDoc exists elsewhere):

    • the_title (×4 in deprecated.php) → canonical PHPDoc in wp-includes/post-template.php:166-173. All other call sites across core already have xrefs. The 4 deprecated.php occurrences need /** This filter is documented in wp-includes/post-template.php */.
    • link_category (×1 in deprecated.php:1063) → canonical PHPDoc in wp-includes/bookmark-template.php:273-279. Needs xref.

    Need own PHPDoc (single occurrence, no canonical location):

    • attachment_max_dims, attachment_icon, attachment_innerHTML — single occurrence each, deprecated functions
    • {$boundary}_post_rel_link — 1 occurrence in deprecated.php (also 1 in link-template.php as {$adjacent}_post_rel_link, different dynamic name but same pattern — needs investigation)
    • index_rel_link, parent_post_rel_link — single occurrence each
    • extra_theme_headers — single occurrence, no modern equivalent
    • delete_usermeta, deleted_usermeta, update_usermeta, added_usermeta, updated_usermeta — single occurrence each, deprecated hooks with no modern equivalent
    • graceful_fail, graceful_fail_template — single occurrence each, deprecated
  3. apermo commented on Mar 8, 2026

    @apermo
    OwnerAuthor

    Won't fix — deprecated hooks with no active use. Added xrefs where a canonical PHPDoc exists (the_title, link_category) in PR WordPress#11205. New PHPDoc blocks for the remaining deprecated-only hooks would add review noise without practical value.

  4. added
    wontfixAcknowledged but not worth the review effort
    on Mar 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    wontfixAcknowledged but not worth the review effort

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions