diff --git a/src/wp-admin/includes/class-wp-list-table.php b/src/wp-admin/includes/class-wp-list-table.php index f85bd8981540d..e8d505728a939 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,29 +73,35 @@ class WP_List_Table { * The view switcher modes. * * @since 4.1.0 - * @var array + * + * @var array */ protected $modes = array(); /** * Stores the value returned by ::get_column_info(). * - * @since 4.1.0 - * @var array|null + * @since 4.2.0 + * + * @var array|null */ protected $_column_headers; /** * List of private properties made readable for backward compatibility. * - * @var array + * @since 4.2.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.2.0 + * + * @var string[] */ protected $compat_methods = array( 'set_pagination_args', @@ -116,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 3.2.0 * * @param array|string $args { * Array or string of arguments. @@ -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 4.2.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 4.2.0 + * + * @param object|array $item The current item. */ protected function column_cb( $item ) {} 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..6274a54767c20 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. * @@ -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{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;