Make WordPress Core

Opened 3 years ago

Closed 21 months ago

#50734 closed enhancement (fixed)

Document common values for hook names that contain dynamic portions

Reported by: johnbillion's profile johnbillion Owned by:
Milestone: 5.8 Priority: normal
Severity: normal Version:
Component: Plugins Keywords:
Focuses: docs Cc:

Description

The names of many hooks in WordPress core contain a dynamic portion, for example manage_{$post->post_type}_posts_custom_column.

This can make it is difficult for developers to find the documentation relating to such a hook. For example, searching the Developer Resources site for `manage_page_posts_custom_column` returns no results despite it being a valid hook name. I've seen this happen in practice when working with both new and seasoned developers.

A few hooks include documentation which lists possible values, which allows them to appear in search results on the dev site. For example searching for `load-post-new.php` correctly shows the documentation for the load-{$pagenow} hook.

We should formalise this sort of documentation of potential values for dynamic hook names in order to make it easier for developers to find documentation. This won't be exhaustive of course, but it can cover common values.

There was some discussion on #37748 about doing this, but it didn't go anywhere.

Ideally these potential hook names would be list in a dedicated tag (eg. @hook) so that developer tools that work with the docs can understand them.

 * @hook manage_page_posts_custom_column
 * @hook manage_post_posts_custom_column
 * @hook manage_attachment_posts_custom_column
 */
do_action( "manage_{$post->post_type}_posts_custom_column" );

Thoughts?

Change History (7)

This ticket was mentioned in Slack in #docs by johnbillion. View the logs.


2 years ago

#2 @johnbillion
2 years ago

In 50505:

Docs: Add examples of possible names for various hooks whose name contains a dynamic portion.

This provides greater discoverability of such hooks in search results on the Code Reference site as well as increased clarity when reading the source.

See #50734, #52628

#3 @SergeyBiryukov
2 years ago

  • Milestone changed from Awaiting Review to 5.8

#4 @desrosj
21 months ago

@johnbillion Do you recall if [50505] addressed all of the instance in Core where an example was missing? If so, I'm thinking that this gets closed as fixed, and discussion moves to a Make Core proposal post with a Meta ticket to update the handbook after a consensus is reached.

#5 @johnbillion
21 months ago

No, there are plenty more. Happy to close this and open a follow-up for 5.9, make post, and handbook update.

#6 @desrosj
21 months ago

  • Keywords 2nd-opinion removed

Sounds good to me!

#7 @lukecarbis
21 months ago

  • Resolution set to fixed
  • Status changed from new to closed
Note: See TracTickets for help on using tickets.