Skip to content

Hooks/Docs: Missing PHPDoc on deprecated hooks and legacy load-*.php actions in wp-admin (9 hooks) #27

Closed as not planned

Description

@apermo

Summary

9 hook calls in wp-admin/includes/deprecated.php and wp-admin/admin.php have no PHPDoc block.


wp-admin/includes/deprecated.php — Filters (3) + Action (1)

get_editable_authors (line 270) — in deprecated get_editable_authors(). Deprecated since 2.3.0 with no direct replacement.

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

get_others_drafts (line 715) — in deprecated get_others_unpublished_posts(). Deprecated since 2.3.0.

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

wp_create_thumbnail (line 1137) — in deprecated wp_create_thumbnail(). Deprecated since 3.5.0, use WP_Image_Editor.

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

pre_user_search (line 560, do_action_ref_array) — in deprecated WP_User_Search::query(). Deprecated since 3.1.0.

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

All four need a minimal PHPDoc with @since, @deprecated, and @param tags. None have a modern equivalent to cross-reference.


wp-admin/admin.php — Legacy page-load actions (5)

Five do_action() calls fire legacy hyphenated page-load hooks for pages that were renamed or removed. They have no PHPDoc:

https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-admin/admin.php#L398
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-admin/admin.php#L400
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-admin/admin.php#L404
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-admin/admin.php#L406
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-admin/admin.php#L409

do_action( 'load-page-new.php' );
do_action( 'load-page.php' );
do_action( 'load-categories.php' );
do_action( 'load-edit-link-categories.php' );
do_action( 'load-edit-tags.php' );

These are legacy aliases for the dynamic load-{$page} hook. Each needs a /** This action is documented in wp-admin/admin.php */ cross-reference pointing to the primary load-{$pagenow} hook, or a minimal PHPDoc of its own if Weston prefers.


Fix approach

  • deprecated.php hooks: add @since, @deprecated X.X.0, and @param PHPDoc blocks.
  • admin.php legacy load hooks: add cross-reference comments pointing to the primary load-{$pagenow} PHPDoc in the same file.

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:

    Legacy load-*.php hooks (5 in admin.php):

    • load-page-new.php, load-page.php, load-categories.php, load-edit-link-categories.php, load-edit-tags.php — single occurrence each. These are legacy aliases for the dynamic load-{$pagenow} hook. Best approach: add /** This action is documented in wp-admin/admin.php */ xref pointing to the primary load-{$pagenow} PHPDoc earlier in the same file.

    Deprecated hooks (4 in wp-admin/includes/deprecated.php):

    • get_editable_authors, get_others_drafts, wp_create_thumbnail, pre_user_search — single occurrence each, no modern equivalent. Need own PHPDoc with @since, @deprecated, @param.
  3. apermo commented on Mar 8, 2026

    @apermo
    OwnerAuthor

    Partial fix

    The 5 legacy load-*.php hooks in wp-admin/admin.php are fixed in PR WordPress#11205 (tracked separately as #37).

    Remaining (4 hooks): The deprecated hooks in wp-admin/includes/deprecated.php still need their own PHPDoc blocks with @since, @deprecated, and @param tags:

    • get_editable_authors (line 270)
    • get_others_drafts (line 715)
    • pre_user_search (line 560)
    • wp_create_thumbnail (line 1137)
  4. apermo commented on Mar 8, 2026

    @apermo
    OwnerAuthor

    Won't fix — deprecated hooks with no active use. The 5 legacy load-*.php hooks were fixed in PR WordPress#11205. The 4 remaining deprecated hooks in wp-admin/includes/deprecated.php would add review noise without practical value.

  5. 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