Docs: Improve docblocks in WP_List_Table and WP_Plugins_List_Table

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

@@ -19,30 +19,34 @@ class WP_List_Table {
 	 * The current list of items.
 	 *
 	 * @since 3.1.0
-	 * @var array
+	 *
+	 * @var array<int|string, mixed>
 	 */
 	public $items;
 
 	/**
 	 * Various information about the current table.
 	 *
 	 * @since 3.1.0
-	 * @var array
+	 *
+	 * @var array<string, mixed>
 	 */
 	protected $_args;
 
 	/**
 	 * Various information needed for displaying the pagination.
 	 *
 	 * @since 3.1.0
-	 * @var array
+	 *
+	 * @var array<string, mixed>
 	 */
 	protected $_pagination_args = array();
 
 	/**
 	 * The current screen.
 	 *
 	 * @since 3.1.0
+	 *
 	 * @var WP_Screen
 	 */
 	protected $screen;
@@ -51,14 +55,16 @@ class WP_List_Table {
 	 * Cached bulk actions.
 	 *
 	 * @since 3.1.0
-	 * @var array
+	 *
+	 * @var array<string, string|array<string, string>>|null
 	 */
 	private $_actions;
 
 	/**
 	 * 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<string, string>
 	 */
 	protected $modes = array();
 
 	/**
 	 * Stores the value returned by ::get_column_info().
 	 *
-	 * @since 4.1.0
-	 * @var array|null
+	 * @since 4.2.0
+	 *
+	 * @var array<int, array|string>|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 ) {}