From 50d36b28baebae5c59165869727532b7b253df63 Mon Sep 17 00:00:00 2001 From: Huzaifa Al Mesbah Date: Fri, 20 Feb 2026 21:27:19 +0600 Subject: [PATCH 1/7] Docs: Improve docblocks in WP_Plugins_List_Table - Add missing @since tags to all overridden methods - Add summary descriptions to all previously bare docblocks - Fix @return types to match parent WP_List_Table signatures - Replace vague array types with precise generics (array, array, etc.) - Add descriptions to all bare @global, @param, and @return tags - Remove @return void tags (not used in WordPress core convention) - Align @param and @return descriptions with parent class phrasing --- .../includes/class-wp-plugins-list-table.php | 134 +++++++++++++----- 1 file changed, 98 insertions(+), 36 deletions(-) diff --git a/src/wp-admin/includes/class-wp-plugins-list-table.php b/src/wp-admin/includes/class-wp-plugins-list-table.php index c4866076f984d..3a4684639c3fb 100644 --- a/src/wp-admin/includes/class-wp-plugins-list-table.php +++ b/src/wp-admin/includes/class-wp-plugins-list-table.php @@ -63,27 +63,39 @@ public function __construct( $args = array() ) { } /** - * @return array + * Gets the CSS classes for the list table element. + * + * @since 3.1.0 + * + * @return string[] Array of CSS classes for the table tag. */ protected function get_table_classes() { return array( 'widefat', $this->_args['plural'] ); } /** - * @return bool + * Checks whether the current user can manage plugins for this screen. + * + * @since 3.1.0 + * + * @return bool Whether the current user can activate plugins. */ public function ajax_user_can() { return current_user_can( 'activate_plugins' ); } /** - * @global string $status - * @global array $plugins - * @global array $totals - * @global int $page - * @global string $orderby - * @global string $order - * @global string $s + * Prepares the list of items for displaying. + * + * @since 3.1.0 + * + * @global string $status Current plugin status filter slug. + * @global array> $plugins Array of plugin data arrays grouped by status. + * @global array $totals Count of plugins for each status group. + * @global int $page Current page number. + * @global string $orderby Column name to sort by. + * @global string $order Sort direction, 'ASC' or 'DESC'. + * @global string $s URL-encoded search term. */ public function prepare_items() { global $status, $plugins, $totals, $page, $orderby, $order, $s; @@ -364,10 +376,14 @@ public function prepare_items() { } /** + * Callback to filter plugins by a search term. + * + * @since 3.1.0 + * * @global string $s URL encoded search term. * - * @param array $plugin - * @return bool + * @param array $plugin Plugin data array to check against the search term. + * @return bool True if the plugin matches the search term, false otherwise. */ public function _search_callback( $plugin ) { global $s; @@ -382,11 +398,16 @@ public function _search_callback( $plugin ) { } /** - * @global string $orderby - * @global string $order - * @param array $plugin_a - * @param array $plugin_b - * @return int + * Callback to sort plugins by a given column. + * + * @since 3.1.0 + * + * @global string $orderby The column name to sort by. + * @global string $order The sort direction ('ASC' or 'DESC'). + * + * @param array $plugin_a First plugin data array to compare. + * @param array $plugin_b Second plugin data array to compare. + * @return int Negative if $plugin_a sorts before $plugin_b, positive if after, 0 if equal. */ public function _order_callback( $plugin_a, $plugin_b ) { global $orderby, $order; @@ -406,7 +427,11 @@ public function _order_callback( $plugin_a, $plugin_b ) { } /** - * @global array $plugins + * Message to be displayed when there are no items. + * + * @since 3.1.0 + * + * @global array> $plugins Array of plugin data arrays grouped by status. */ public function no_items() { global $plugins; @@ -459,9 +484,13 @@ public function search_box( $text, $input_id ) { } /** - * @global string $status + * Gets the list of columns for this list table. + * + * @since 3.1.0 + * + * @global string $status Current plugin status filter slug. * - * @return string[] Array of column titles keyed by their column name. + * @return array An associative array of columns. */ public function get_columns() { global $status; @@ -480,16 +509,25 @@ public function get_columns() { } /** - * @return array + * Gets the list of sortable columns for this list table. + * + * @since 3.1.0 + * + * @return array|string> An associative array of sortable columns. */ protected function get_sortable_columns() { return array(); } /** - * @global array $totals - * @global string $status - * @return array + * Gets an associative array of status filter links for the views area. + * + * @since 3.1.0 + * + * @global array $totals Count of plugins for each status group. + * @global string $status Current plugin status filter slug. + * + * @return array An associative array of views. */ protected function get_views() { global $totals, $status; @@ -616,8 +654,13 @@ protected function get_views() { } /** - * @global string $status - * @return array + * Gets the available bulk actions for the plugins list table. + * + * @since 3.1.0 + * + * @global string $status Current plugin status filter slug. + * + * @return array> An associative array of bulk actions. */ protected function get_bulk_actions() { global $status; @@ -655,8 +698,14 @@ protected function get_bulk_actions() { } /** - * @global string $status - * @param string $which + * Displays the bulk actions dropdown. + * + * @since 3.1.0 + * + * @global string $status Current plugin status filter slug. + * + * @param string $which The location of the bulk actions: Either 'top' or 'bottom'. + * This is designated as optional for backward compatibility. */ public function bulk_actions( $which = '' ) { global $status; @@ -669,8 +718,13 @@ public function bulk_actions( $which = '' ) { } /** - * @global string $status - * @param string $which + * Displays extra table navigation for the plugins list table. + * + * @since 3.1.0 + * + * @global string $status Current plugin status filter slug. + * + * @param string $which The location: 'top' or 'bottom'. */ protected function extra_tablenav( $which ) { global $status; @@ -700,7 +754,11 @@ protected function extra_tablenav( $which ) { } /** - * @return string + * Gets the current action selected from the bulk actions dropdown. + * + * @since 3.1.0 + * + * @return string|false The action name. False if no action was selected. */ public function current_action() { if ( isset( $_POST['clear-recent-list'] ) ) { @@ -715,7 +773,7 @@ public function current_action() { * * @since 3.1.0 * - * @global string $status + * @global string $status Current plugin status filter slug. */ public function display_rows() { global $status; @@ -730,12 +788,16 @@ public function display_rows() { } /** - * @global string $status - * @global int $page - * @global string $s - * @global array $totals + * Generates the markup for a single plugin row. + * + * @since 3.1.0 + * + * @global string $status Current plugin status filter slug. + * @global int $page Current page number. + * @global string $s URL-encoded search term. + * @global array $totals Count of plugins for each status group. * - * @param array $item + * @param array $item The current item. An array containing the plugin file path and plugin data. */ public function single_row( $item ) { global $status, $page, $s, $totals; From e1ae8dee9bdffd54b15ac63d652ee95ec378067f Mon Sep 17 00:00:00 2001 From: Huzaifa Al Mesbah Date: Fri, 20 Feb 2026 21:34:44 +0600 Subject: [PATCH 2/7] Docs: Improve docblocks in WP_List_Table - Improve @var types on all class properties from bare 'array' to precise generics (array, array, etc.) - Add missing @since tags to compat_fields and compat_methods properties - Add missing descriptions to all bare @param tags: view_switcher(), print_column_headers(), column_default(), column_cb() - Add full docblocks to column_default() and column_cb() which had no summary line or @since tag - Fix missing periods on summary lines: has_items(), no_items(), display_tablenav() - Fix display_tablenav() @param tag incorrectly placed on same line as @since with no blank line separator - Add blank lines between @since and @var tags for consistency --- src/wp-admin/includes/class-wp-list-table.php | 53 +++++++++++++------ 1 file changed, 37 insertions(+), 16 deletions(-) diff --git a/src/wp-admin/includes/class-wp-list-table.php b/src/wp-admin/includes/class-wp-list-table.php index 0795da27535c6..511f8ce8ac5c5 100644 --- a/src/wp-admin/includes/class-wp-list-table.php +++ b/src/wp-admin/includes/class-wp-list-table.php @@ -19,7 +19,8 @@ class WP_List_Table { * The current list of items. * * @since 3.1.0 - * @var array + * + * @var array */ public $items; @@ -27,7 +28,8 @@ class WP_List_Table { * Various information about the current table. * * @since 3.1.0 - * @var array + * + * @var array */ protected $_args; @@ -35,7 +37,8 @@ class WP_List_Table { * Various information needed for displaying the pagination. * * @since 3.1.0 - * @var array + * + * @var array */ protected $_pagination_args = array(); @@ -43,6 +46,7 @@ class WP_List_Table { * The current screen. * * @since 3.1.0 + * * @var WP_Screen */ protected $screen; @@ -51,7 +55,8 @@ class WP_List_Table { * Cached bulk actions. * * @since 3.1.0 - * @var array + * + * @var array>|null */ private $_actions; @@ -59,6 +64,7 @@ class WP_List_Table { * Cached pagination output. * * @since 3.1.0 + * * @var string */ private $_pagination; @@ -67,7 +73,8 @@ class WP_List_Table { * The view switcher modes. * * @since 4.1.0 - * @var array + * + * @var array */ protected $modes = array(); @@ -75,21 +82,26 @@ class WP_List_Table { * Stores the value returned by ::get_column_info(). * * @since 4.1.0 - * @var array|null + * + * @var array|null */ protected $_column_headers; /** * List of private properties made readable for backward compatibility. * - * @var array + * @since 4.0.0 + * + * @var string[] */ protected $compat_fields = array( '_args', '_pagination_args', 'screen', '_actions', '_pagination' ); /** * List of private/protected methods made readable for backward compatibility. * - * @var array + * @since 4.0.0 + * + * @var string[] */ protected $compat_methods = array( 'set_pagination_args', @@ -348,7 +360,7 @@ public function get_pagination_arg( $key ) { } /** - * Determines whether the table has items to display or not + * Determines whether the table has items to display or not. * * @since 3.1.0 * @@ -359,7 +371,7 @@ public function has_items() { } /** - * Message to be displayed when there are no items + * Message to be displayed when there are no items. * * @since 3.1.0 */ @@ -790,7 +802,7 @@ protected function months_dropdown( $post_type ) { * * @since 3.1.0 * - * @param string $current_mode + * @param string $current_mode The current view mode slug, e.g. 'list' or 'excerpt'. */ protected function view_switcher( $current_mode ) { ?> @@ -1389,7 +1401,7 @@ public function get_column_count() { * * @since 3.1.0 * - * @param bool $with_id Whether to set the ID attribute or not + * @param bool $with_id Whether to set the ID attribute or not. Default true. */ public function print_column_headers( $with_id = true ) { list( $columns, $hidden, $sortable, $primary ) = $this->get_column_info(); @@ -1657,9 +1669,10 @@ protected function get_table_classes() { } /** - * Generates the table navigation above or below the table + * Generates the table navigation above or below the table. * * @since 3.1.0 + * * @param string $which The location of the navigation: Either 'top' or 'bottom'. */ protected function display_tablenav( $which ) { @@ -1736,13 +1749,21 @@ public function single_row( $item ) { } /** - * @param object|array $item - * @param string $column_name + * Handles an unknown column. + * + * @since 3.1.0 + * + * @param object|array $item The current item. + * @param string $column_name Name of the column. */ protected function column_default( $item, $column_name ) {} /** - * @param object|array $item + * Handles the checkbox column output. + * + * @since 3.1.0 + * + * @param object|array $item The current item. */ protected function column_cb( $item ) {} From daa93695a33dbc42a668d34e018e548850ed4cf8 Mon Sep 17 00:00:00 2001 From: Huzaifa Al Mesbah Date: Sun, 22 Feb 2026 12:21:22 +0600 Subject: [PATCH 3/7] refactor: use array shape for $item param phpdoc Co-authored-by: Weston Ruter --- src/wp-admin/includes/class-wp-plugins-list-table.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/wp-admin/includes/class-wp-plugins-list-table.php b/src/wp-admin/includes/class-wp-plugins-list-table.php index 3a4684639c3fb..f3d2966fe720f 100644 --- a/src/wp-admin/includes/class-wp-plugins-list-table.php +++ b/src/wp-admin/includes/class-wp-plugins-list-table.php @@ -797,7 +797,7 @@ public function display_rows() { * @global string $s URL-encoded search term. * @global array $totals Count of plugins for each status group. * - * @param array $item The current item. An array containing the plugin file path and plugin data. + * @param array{string, array} $item The current item. An array containing the plugin file path and plugin data. */ public function single_row( $item ) { global $status, $page, $s, $totals; From 9c8df2f85a0c7b5a035773e8d1717a81d6ad533d Mon Sep 17 00:00:00 2001 From: Weston Ruter Date: Mon, 23 Feb 2026 18:27:35 -0800 Subject: [PATCH 4/7] Correct @since tags in WP_List_Table - Update $_column_headers from @since 4.1.0 to 4.2.0 - Update $compat_fields from @since 4.0.0 to 4.2.0 - Update $compat_methods from @since 4.0.0 to 4.2.0 - Update column_default() from @since 3.1.0 to 4.2.0 - Update column_cb() from @since 3.1.0 to 4.2.0 These properties and methods were introduced in 4.2.0 as part of #30799 and #30891. Co-authored-by: gemini-cli <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- src/wp-admin/includes/class-wp-list-table.php | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/wp-admin/includes/class-wp-list-table.php b/src/wp-admin/includes/class-wp-list-table.php index 511f8ce8ac5c5..408cf7da1e15a 100644 --- a/src/wp-admin/includes/class-wp-list-table.php +++ b/src/wp-admin/includes/class-wp-list-table.php @@ -81,7 +81,7 @@ class WP_List_Table { /** * Stores the value returned by ::get_column_info(). * - * @since 4.1.0 + * @since 4.2.0 * * @var array|null */ @@ -90,7 +90,7 @@ class WP_List_Table { /** * List of private properties made readable for backward compatibility. * - * @since 4.0.0 + * @since 4.2.0 * * @var string[] */ @@ -99,7 +99,7 @@ class WP_List_Table { /** * List of private/protected methods made readable for backward compatibility. * - * @since 4.0.0 + * @since 4.2.0 * * @var string[] */ @@ -1751,7 +1751,7 @@ public function single_row( $item ) { /** * Handles an unknown column. * - * @since 3.1.0 + * @since 4.2.0 * * @param object|array $item The current item. * @param string $column_name Name of the column. @@ -1761,7 +1761,7 @@ protected function column_default( $item, $column_name ) {} /** * Handles the checkbox column output. * - * @since 3.1.0 + * @since 4.2.0 * * @param object|array $item The current item. */ From 5fbf3567734e5b4a081a43bcb569a31389b124b6 Mon Sep 17 00:00:00 2001 From: Weston Ruter Date: Mon, 23 Feb 2026 18:33:54 -0800 Subject: [PATCH 5/7] Docs: Update @since tag for WP_List_Table::__construct() The __construct method was added in 4.0.0 to replace the PHP 4-style constructor. Co-authored-by: gemini-cli <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- src/wp-admin/includes/class-wp-list-table.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/wp-admin/includes/class-wp-list-table.php b/src/wp-admin/includes/class-wp-list-table.php index 408cf7da1e15a..50dda192fdf37 100644 --- a/src/wp-admin/includes/class-wp-list-table.php +++ b/src/wp-admin/includes/class-wp-list-table.php @@ -128,7 +128,7 @@ class WP_List_Table { * The child class should call this constructor from its own constructor to override * the default $args. * - * @since 3.1.0 + * @since 4.0.0 * * @param array|string $args { * Array or string of arguments. From 597be1b569314a5f8e056c3ea06d8ac2cf1f9563 Mon Sep 17 00:00:00 2001 From: Weston Ruter Date: Mon, 23 Feb 2026 18:39:19 -0800 Subject: [PATCH 6/7] Docs: Correct @since tags in WP_List_Table and WP_Plugins_List_Table - WP_List_Table::__construct(): Update from 3.1.0 to 3.2.0. - WP_List_Table::$_column_headers: Update from 4.1.0 to 4.2.0. - WP_List_Table::$compat_fields: Update from 4.0.0 to 4.2.0. - WP_List_Table::$compat_methods: Update from 4.0.0 to 4.2.0. - WP_List_Table::column_default(): Update from 3.1.0 to 4.2.0. - WP_List_Table::column_cb(): Update from 3.1.0 to 4.2.0. - WP_Plugins_List_Table::__construct(): Update from 3.1.0 to 3.2.0. These properties and methods were historically introduced or renamed in the specified versions. Co-authored-by: gemini-cli <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- src/wp-admin/includes/class-wp-list-table.php | 2 +- src/wp-admin/includes/class-wp-plugins-list-table.php | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/wp-admin/includes/class-wp-list-table.php b/src/wp-admin/includes/class-wp-list-table.php index 50dda192fdf37..10adeb8ee92e8 100644 --- a/src/wp-admin/includes/class-wp-list-table.php +++ b/src/wp-admin/includes/class-wp-list-table.php @@ -128,7 +128,7 @@ class WP_List_Table { * The child class should call this constructor from its own constructor to override * the default $args. * - * @since 4.0.0 + * @since 3.2.0 * * @param array|string $args { * Array or string of arguments. diff --git a/src/wp-admin/includes/class-wp-plugins-list-table.php b/src/wp-admin/includes/class-wp-plugins-list-table.php index f3d2966fe720f..dd1af6d198d9a 100644 --- a/src/wp-admin/includes/class-wp-plugins-list-table.php +++ b/src/wp-admin/includes/class-wp-plugins-list-table.php @@ -27,7 +27,7 @@ class WP_Plugins_List_Table extends WP_List_Table { /** * Constructor. * - * @since 3.1.0 + * @since 3.2.0 * * @see WP_List_Table::__construct() for more information on default arguments. * From 757950f4b83d63bb66bf6c815b2d0e84a7426cf0 Mon Sep 17 00:00:00 2001 From: Weston Ruter Date: Mon, 23 Feb 2026 18:55:41 -0800 Subject: [PATCH 7/7] Docs: Refine $plugins global type in WP_Plugins_List_Table The $plugins global is a 3-level array: an associative array where keys are statuses (e.g., 'all', 'active'), and values are associative arrays of plugin data (keyed by plugin file). Co-authored-by: gemini-cli <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- .../includes/class-wp-plugins-list-table.php | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/wp-admin/includes/class-wp-plugins-list-table.php b/src/wp-admin/includes/class-wp-plugins-list-table.php index dd1af6d198d9a..6274a54767c20 100644 --- a/src/wp-admin/includes/class-wp-plugins-list-table.php +++ b/src/wp-admin/includes/class-wp-plugins-list-table.php @@ -89,13 +89,13 @@ public function ajax_user_can() { * * @since 3.1.0 * - * @global string $status Current plugin status filter slug. - * @global array> $plugins Array of plugin data arrays grouped by status. - * @global array $totals Count of plugins for each status group. - * @global int $page Current page number. - * @global string $orderby Column name to sort by. - * @global string $order Sort direction, 'ASC' or 'DESC'. - * @global string $s URL-encoded search term. + * @global string $status Current plugin status filter slug. + * @global array>> $plugins Array of plugin data arrays grouped by status. + * @global array $totals Count of plugins for each status group. + * @global int $page Current page number. + * @global string $orderby Column name to sort by. + * @global string $order Sort direction, 'ASC' or 'DESC'. + * @global string $s URL-encoded search term. */ public function prepare_items() { global $status, $plugins, $totals, $page, $orderby, $order, $s; @@ -431,7 +431,7 @@ public function _order_callback( $plugin_a, $plugin_b ) { * * @since 3.1.0 * - * @global array> $plugins Array of plugin data arrays grouped by status. + * @global array>> $plugins Array of plugin data arrays grouped by status. */ public function no_items() { global $plugins;