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


git-svn-id: https://develop.svn.wordpress.org/trunk@50505 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-admin/async-upload.php

@@ -119,8 +119,14 @@ if ( $_REQUEST['short'] ) {
 	/**
 	 * Filters the returned ID of an uploaded attachment.
 	 *
-	 * The dynamic portion of the hook name, `$type`, refers to the attachment type,
-	 * such as 'image', 'audio', 'video', 'file', etc.
+	 * The dynamic portion of the hook name, `$type`, refers to the attachment type.
+	 *
+	 * Possible hook names include:
+	 *
+	 *  - `async_upload_audio`
+	 *  - `async_upload_file`
+	 *  - `async_upload_image`
+	 *  - `async_upload_video`
 	 *
 	 * @since 2.5.0
 	 *

src/wp-admin/edit-tag-form.php

@@ -60,6 +60,11 @@ require_once ABSPATH . 'wp-admin/includes/edit-tag-messages.php';
  * The dynamic portion of the hook name, `$taxonomy`, refers to
  * the taxonomy slug.
  *
+ * Possible hook names include:
+ *
+ *  - `category_pre_edit_form`
+ *  - `post_tag_pre_edit_form`
+ *
  * @since 3.0.0
  *
  * @param WP_Term $tag      Current taxonomy term object.
@@ -96,6 +101,11 @@ if ( $message ) {
  *
  * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
  *
+ * Possible hook names include:
+ *
+ *  - `category_term_edit_form_tag`
+ *  - `post_tag_term_edit_form_tag`
+ *
  * @since 3.7.0
  */
 do_action( "{$taxonomy}_term_edit_form_tag" );
@@ -115,6 +125,11 @@ wp_nonce_field( 'update-tag_' . $tag_ID );
  *
  * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
  *
+ * Possible hook names include:
+ *
+ *  - `category_term_edit_form_top`
+ *  - `post_tag_term_edit_form_top`
+ *
  * @since 4.5.0
  *
  * @param WP_Term $tag      Current taxonomy term object.
@@ -229,6 +244,11 @@ if ( isset( $tag->name ) ) {
 		 * The dynamic portion of the hook name, `$taxonomy`, refers to
 		 * the taxonomy slug.
 		 *
+		 * Possible hook names include:
+		 *
+		 *  - `category_edit_form_fields`
+		 *  - `post_tag_edit_form_fields`
+		 *
 		 * @since 3.0.0
 		 *
 		 * @param WP_Term $tag      Current taxonomy term object.
@@ -261,6 +281,11 @@ if ( 'category' === $taxonomy ) {
  *
  * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
  *
+ * Possible hook names include:
+ *
+ *  - `category_edit_form`
+ *  - `post_tag_edit_form`
+ *
  * @since 3.0.0
  *
  * @param WP_Term $tag      Current taxonomy term object.

src/wp-admin/edit-tags.php

@@ -414,6 +414,11 @@ if ( $can_edit_terms ) {
 	 *
 	 * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
 	 *
+	 * Possible hook names include:
+	 *
+	 *  - `category_pre_add_form`
+	 *  - `post_tag_pre_add_form`
+	 *
 	 * @since 3.0.0
 	 *
 	 * @param string $taxonomy The taxonomy slug.
@@ -430,6 +435,11 @@ if ( $can_edit_terms ) {
 	 *
 	 * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
 	 *
+	 * Possible hook names include:
+	 *
+	 *  - `category_term_new_form_tag`
+	 *  - `post_tag_term_new_form_tag`
+	 *
 	 * @since 3.7.0
 	 */
 	do_action( "{$taxonomy}_term_new_form_tag" );
@@ -522,6 +532,11 @@ if ( $can_edit_terms ) {
 	 *
 	 * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
 	 *
+	 * Possible hook names include:
+	 *
+	 *  - `category_add_form_fields`
+	 *  - `post_tag_add_form_fields`
+	 *
 	 * @since 3.0.0
 	 *
 	 * @param string $taxonomy The taxonomy slug.
@@ -570,6 +585,11 @@ if ( $can_edit_terms ) {
 	 *
 	 * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
 	 *
+	 * Possible hook names include:
+	 *
+	 *  - `category_add_form`
+	 *  - `post_tag_add_form`
+	 *
 	 * @since 3.0.0
 	 *
 	 * @param string $taxonomy The taxonomy slug.
@@ -638,6 +658,11 @@ endif;
  *
  * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
  *
+ * Possible hook names include:
+ *
+ *  - `after-category-table`
+ *  - `after-post_tag-table`
+ *
  * @since 3.0.0
  *
  * @param string $taxonomy The taxonomy name.

src/wp-admin/includes/class-wp-automatic-updater.php

@@ -182,7 +182,9 @@ class WP_Automatic_Updater {
 		 * Filters whether to automatically update core, a plugin, a theme, or a language.
 		 *
 		 * The dynamic portion of the hook name, `$type`, refers to the type of update
-		 * being checked. Potential hook names include:
+		 * being checked.
+		 *
+		 * Possible hook names include:
 		 *
 		 *  - `auto_update_core`
 		 *  - `auto_update_plugin`

src/wp-admin/includes/class-wp-plugin-install-list-table.php

@@ -213,7 +213,14 @@ class WP_Plugin_Install_List_Table extends WP_List_Table {
 		 * Filters API request arguments for each Add Plugins screen tab.
 		 *
 		 * The dynamic portion of the hook name, `$tab`, refers to the plugin install tabs.
-		 * Default tabs include 'featured', 'popular', 'recommended', 'favorites', and 'upload'.
+		 *
+		 * Possible hook names include:
+		 *
+		 *  - `install_plugins_table_api_args_favorites`
+		 *  - `install_plugins_table_api_args_featured`
+		 *  - `install_plugins_table_api_args_popular`
+		 *  - `install_plugins_table_api_args_recommended`
+		 *  - `install_plugins_table_api_args_upload`
 		 *
 		 * @since 3.7.0
 		 *

src/wp-admin/includes/class-wp-posts-list-table.php

@@ -632,6 +632,11 @@ class WP_Posts_List_Table extends WP_List_Table {
 		 * The dynamic portion of the hook name, `$post_type`, refers to the post
 		 * type slug.
 		 *
+		 * Possible hook names include:
+		 *
+		 *  - `manage_taxonomies_for_post_columns`
+		 *  - `manage_taxonomies_for_page_columns`
+		 *
 		 * @since 3.5.0
 		 *
 		 * @param string[] $taxonomies Array of taxonomy names to show columns for.
@@ -687,6 +692,11 @@ class WP_Posts_List_Table extends WP_List_Table {
 		 *
 		 * The dynamic portion of the hook name, `$post_type`, refers to the post type slug.
 		 *
+		 * Possible hook names include:
+		 *
+		 *  - `manage_post_posts_columns`
+		 *  - `manage_page_posts_columns`
+		 *
 		 * @since 3.0.0
 		 *
 		 * @param string[] $post_columns An associative array of column headings.
@@ -1274,6 +1284,11 @@ class WP_Posts_List_Table extends WP_List_Table {
 		 *
 		 * The dynamic portion of the hook name, `$post->post_type`, refers to the post type.
 		 *
+		 * Possible hook names include:
+		 *
+		 *  - `manage_post_posts_custom_column`
+		 *  - `manage_page_posts_custom_column`
+		 *
 		 * @since 3.1.0
 		 *
 		 * @param string $column_name The name of the column to display.

src/wp-admin/includes/class-wp-terms-list-table.php

@@ -526,6 +526,11 @@ class WP_Terms_List_Table extends WP_List_Table {
 		 *
 		 * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
 		 *
+		 * Possible hook names include:
+		 *
+		 *  - `category_row_actions`
+		 *  - `post_tag_row_actions`
+		 *
 		 * @since 3.0.0
 		 *
 		 * @param string[] $actions An array of action links to be displayed. Default
@@ -616,6 +621,11 @@ class WP_Terms_List_Table extends WP_List_Table {
 		 * The dynamic portion of the hook name, `$this->screen->taxonomy`,
 		 * refers to the slug of the current taxonomy.
 		 *
+		 * Possible hook names include:
+		 *
+		 *  - `manage_category_custom_column`
+		 *  - `manage_post_tag_custom_column`
+		 *
 		 * @since 2.8.0
 		 *
 		 * @param string $string      Blank string.

src/wp-admin/includes/class-wp-theme-install-list-table.php

@@ -132,8 +132,16 @@ class WP_Theme_Install_List_Table extends WP_Themes_List_Table {
 		 * Filters API request arguments for each Install Themes screen tab.
 		 *
 		 * The dynamic portion of the hook name, `$tab`, refers to the theme install
-		 * tabs. Default tabs are 'dashboard', 'search', 'upload', 'featured',
-		 * 'new', and 'updated'.
+		 * tab.
+		 *
+		 * Possible hook names include:
+		 *
+		 *  - `install_themes_table_api_args_dashboard`
+		 *  - `install_themes_table_api_args_featured`
+		 *  - `install_themes_table_api_args_new`
+		 *  - `install_themes_table_api_args_search`
+		 *  - `install_themes_table_api_args_updated`
+		 *  - `install_themes_table_api_args_upload`
 		 *
 		 * @since 3.7.0
 		 *

src/wp-admin/includes/file.php

@@ -757,7 +757,8 @@ function _wp_handle_upload( &$file, $overrides, $time, $action ) {
 	 * Filters the data for a file before it is uploaded to WordPress.
 	 *
 	 * The dynamic portion of the hook name, `$action`, refers to the post action.
-	 * Possible filter names include:
+	 *
+	 * Possible hook names include:
 	 *
 	 *  - `wp_handle_sideload_prefilter`
 	 *  - `wp_handle_upload_prefilter`
@@ -773,7 +774,8 @@ function _wp_handle_upload( &$file, $overrides, $time, $action ) {
 	 * Filters the override parameters for a file before it is uploaded to WordPress.
 	 *
 	 * The dynamic portion of the hook name, `$action`, refers to the post action.
-	 * Possible filter names include:
+	 *
+	 * Possible hook names include:
 	 *
 	 *  - `wp_handle_sideload_overrides`
 	 *  - `wp_handle_upload_overrides`

src/wp-admin/includes/media.php

@@ -696,9 +696,14 @@ function get_upload_iframe_src( $type = null, $post_id = null, $tab = null ) {
 	 * The dynamic portion of the hook name, `$type`, refers to the type
 	 * of media uploaded.
 	 *
+	 * Possible hook names include:
+	 *
+	 *  - `image_upload_iframe_src`
+	 *  - `media_upload_iframe_src`
+	 *
 	 * @since 3.0.0
 	 *
-	 * @param string $upload_iframe_src The upload iframe source URL by type.
+	 * @param string $upload_iframe_src The upload iframe source URL.
 	 */
 	$upload_iframe_src = apply_filters( "{$type}_upload_iframe_src", $upload_iframe_src );
 
@@ -893,6 +898,12 @@ function wp_media_upload_handler() {
 			 * The dynamic portion of the hook name, `$type`, refers to the type
 			 * of media being sent.
 			 *
+			 * Possible hook names include:
+			 *
+			 *  - `audio_send_to_editor_url`
+			 *  - `file_send_to_editor_url`
+			 *  - `video_send_to_editor_url`
+			 *
 			 * @since 3.3.0
 			 *
 			 * @param string $html  HTML markup sent to the editor.

src/wp-admin/includes/nav-menu.php

@@ -545,6 +545,11 @@ function wp_nav_menu_item_post_type_meta_box( $object, $box ) {
 				 *
 				 * The dynamic portion of the hook name, `$post_type_name`, refers to the post type name.
 				 *
+				 * Possible hook names include:
+				 *
+				 *  - `nav_menu_items_post_recent`
+				 *  - `nav_menu_items_page_recent`
+				 *
 				 * @since 4.3.0
 				 * @since 4.9.0 Added the `$recent_args` parameter.
 				 *
@@ -633,6 +638,11 @@ function wp_nav_menu_item_post_type_meta_box( $object, $box ) {
 				 * The dynamic portion of the hook name, `$post_type_name`, refers
 				 * to the slug of the current post type.
 				 *
+				 * Possible hook names include:
+				 *
+				 *  - `nav_menu_items_post`
+				 *  - `nav_menu_items_page`
+				 *
 				 * @since 3.2.0
 				 * @since 4.6.0 Converted the `$post_type` parameter to accept a WP_Post_Type object.
 				 *

src/wp-admin/includes/post.php

@@ -1168,8 +1168,11 @@ function wp_edit_posts_query( $q = false ) {
 	 *
 	 * The dynamic portion of the hook name, `$post_type`, refers to the post type.
 	 *
-	 * Some examples of filter hooks generated here include: 'edit_attachment_per_page',
-	 * 'edit_post_per_page', 'edit_page_per_page', etc.
+	 * Possible hook names include:
+	 *
+	 *  - `edit_post_per_page`
+	 *  - `edit_page_per_page`
+	 *  - `edit_attachment_per_page`
 	 *
 	 * @since 3.0.0
 	 *

src/wp-admin/includes/revision.php

@@ -68,8 +68,14 @@ function wp_get_revision_ui_diff( $post, $compare_from, $compare_to ) {
 		/**
 		 * Contextually filter a post revision field.
 		 *
-		 * The dynamic portion of the hook name, `$field`, corresponds to each of the post
-		 * fields of the revision object being iterated over in a foreach statement.
+		 * The dynamic portion of the hook name, `$field`, corresponds to a name of a
+		 * field of the revision object.
+		 *
+		 * Possible hook names include:
+		 *
+		 *  - `_wp_post_revision_field_post_title`
+		 *  - `_wp_post_revision_field_post_content`
+		 *  - `_wp_post_revision_field_post_excerpt`
 		 *
 		 * @since 3.6.0
 		 *

src/wp-admin/media-upload.php

@@ -87,13 +87,19 @@ if ( 'type' === $tab || 'type_url' === $tab || ! array_key_exists( $tab, media_u
 	 * media popup based on the current tab.
 	 *
 	 * The dynamic portion of the hook name, `$type`, refers to the specific
-	 * media upload type. Possible values include 'image', 'audio', 'video',
-	 * 'file', etc.
+	 * media upload type.
 	 *
 	 * The hook only fires if the current `$tab` is 'type' (From Computer),
 	 * 'type_url' (From URL), or, if the tab does not exist (i.e., has not
 	 * been registered via the {@see 'media_upload_tabs'} filter.
 	 *
+	 * Possible hook names include:
+	 *
+	 *  - `media_upload_audio`
+	 *  - `media_upload_file`
+	 *  - `media_upload_image`
+	 *  - `media_upload_video`
+	 *
 	 * @since 2.5.0
 	 */
 	do_action( "media_upload_{$type}" );

src/wp-admin/theme-install.php

@@ -84,8 +84,16 @@ if ( $tab ) {
 	 * Fires before each of the tabs are rendered on the Install Themes page.
 	 *
 	 * The dynamic portion of the hook name, `$tab`, refers to the current
-	 * theme installation tab. Possible values are 'dashboard', 'search', 'upload',
-	 * 'featured', 'new', or 'updated'.
+	 * theme installation tab.
+	 *
+	 * Possible hook names include:
+	 *
+	 *  - `install_themes_pre_dashboard`
+	 *  - `install_themes_pre_featured`
+	 *  - `install_themes_pre_new`
+	 *  - `install_themes_pre_search`
+	 *  - `install_themes_pre_updated`
+	 *  - `install_themes_pre_upload`
 	 *
 	 * @since 2.8.0
 	 */
@@ -251,8 +259,16 @@ if ( $tab ) {
 	 * Fires at the top of each of the tabs on the Install Themes page.
 	 *
 	 * The dynamic portion of the hook name, `$tab`, refers to the current
-	 * theme installation tab. Possible values are 'dashboard', 'search', 'upload',
-	 * 'featured', 'new', or 'updated'.
+	 * theme installation tab.
+	 *
+	 * Possible hook names include:
+	 *
+	 *  - `install_themes_dashboard`
+	 *  - `install_themes_featured`
+	 *  - `install_themes_new`
+	 *  - `install_themes_search`
+	 *  - `install_themes_updated`
+	 *  - `install_themes_upload`
 	 *
 	 * @since 2.8.0
 	 *