[wp-trac] [WordPress Trac] #50734: Document common values for hook names that contain dynamic portions

[WordPress Trac]

#50734: Document common values for hook names that contain dynamic portions
-------------------------+-----------------------------
 Reporter:  johnbillion  |      Owner:  (none)
     Type:  enhancement  |     Status:  new
 Priority:  normal       |  Milestone:  Awaiting Review
Component:  Plugins      |    Version:
 Severity:  normal       |   Keywords:  2nd-opinion
  Focuses:  docs         |
-------------------------+-----------------------------
 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,
 [https://developer.wordpress.org/?s=manage_page_posts_custom_column
 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
 [https://developer.wordpress.org/?s=load-post-new.php 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?

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/50734>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform