Thanks to visit codestin.com
Credit goes to core.trac.wordpress.org

Codestin Search App
Get WordPress

Make WordPress Core

Changeset 62491


Ignore:
Timestamp:
06/11/2026 08:14:31 PM (2 weeks ago)
Author:
westonruter
Message:

Docs: Improve WP_List_Table and WP_Plugins_List_Table docblocks.

Improve the PHPDoc docblocks in WP_List_Table and WP_Plugins_List_Table for accuracy, completeness, and consistency with WordPress core documentation standards. Adds missing @since tags and corrects several existing versions, adds summary descriptions to all previously bare method and property docblocks, and refines type annotations with precise generic array types.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10989.
Follow-up to r30679, r31127, r32642, r32654.

Props huzaifaalmesbah, westonruter, noruzzaman.
See #64896.

Location:
trunk/src/wp-admin/includes
Files:
2 edited

Legend:

Unmodified
Added
Removed

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

    r62400 r62491  
    2020     *
    2121     * @since 3.1.0
    22      * @var array
     22     *
     23     * @var array<int|string, mixed>
    2324     */
    2425    public $items;
    … …  
    2829     *
    2930     * @since 3.1.0
    30      * @var array
     31     *
     32     * @var array<string, mixed>
    3133     */
    3234    protected $_args;
    … …  
    3638     *
    3739     * @since 3.1.0
    38      * @var array
     40     *
     41     * @var array<string, mixed>
    3942     */
    4043    protected $_pagination_args = array();
    … …  
    4447     *
    4548     * @since 3.1.0
     49     *
    4650     * @var WP_Screen
    4751     */
    … …  
    5256     *
    5357     * @since 3.1.0
    54      * @var array
     58     *
     59     * @var array<string, string|array<string, string>>|null
    5560     */
    5661    private $_actions;
    … …  
    6065     *
    6166     * @since 3.1.0
     67     *
    6268     * @var string
    6369     */
    … …  
    6874     *
    6975     * @since 4.1.0
    70      * @var array
     76     *
     77     * @var array<string, string>
    7178     */
    7279    protected $modes = array();
    7380
    7481    /**
    75      * Stores the value returned by ::get_column_info().
    76      *
    77      * @since 4.1.0
    78      * @var array|null
     82     * Stores the value returned by {@see self::get_column_info()}.
     83     *
     84     * @since 4.2.0
     85     *
     86     * @var array<int, array|string>|null
    7987     */
    8088    protected $_column_headers;
    … …  
    8391     * List of private properties made readable for backward compatibility.
    8492     *
    85      * @var array
     93     * @since 4.2.0
     94     *
     95     * @var string[]
    8696     */
    8797    protected $compat_fields = array( '_args', '_pagination_args', 'screen', '_actions', '_pagination' );
    … …  
    90100     * List of private/protected methods made readable for backward compatibility.
    91101     *
    92      * @var array
     102     * @since 4.2.0
     103     *
     104     * @var string[]
    93105     */
    94106    protected $compat_methods = array(
    … …  
    117129     * the default $args.
    118130     *
    119      * @since 3.1.0
     131     * @since 3.2.0
    120132     *
    121133     * @param array|string $args {
    … …  
    349361
    350362    /**
    351      * Determines whether the table has items to display or not
     363     * Determines whether the table has items to display or not.
    352364     *
    353365     * @since 3.1.0
    … …  
    360372
    361373    /**
    362      * Message to be displayed when there are no items
     374     * Message to be displayed when there are no items.
    363375     *
    364376     * @since 3.1.0
    … …  
    791803     * @since 3.1.0
    792804     *
    793      * @param string $current_mode
     805     * @param string $current_mode The current view mode slug, e.g. 'list' or 'excerpt'.
    794806     */
    795807    protected function view_switcher( $current_mode ) {
    … …  
    13901402     * @since 3.1.0
    13911403     *
    1392      * @param bool $with_id Whether to set the ID attribute or not
     1404     * @param bool $with_id Whether to set the ID attribute or not. Default true.
    13931405     */
    13941406    public function print_column_headers( $with_id = true ) {
    … …  
    16581670
    16591671    /**
    1660      * Generates the table navigation above or below the table
    1661      *
    1662      * @since 3.1.0
     1672     * Generates the table navigation above or below the table.
     1673     *
     1674     * @since 3.1.0
     1675     *
    16631676     * @param string $which The location of the navigation: Either 'top' or 'bottom'.
    16641677     */
    … …  
    17371750
    17381751    /**
    1739      * @param object|array $item
    1740      * @param string $column_name
     1752     * Handles an unknown column.
     1753     *
     1754     * @since 4.2.0
     1755     *
     1756     * @param object|array $item        The current item.
     1757     * @param string       $column_name Name of the column.
    17411758     */
    17421759    protected function column_default( $item, $column_name ) {}
    17431760
    17441761    /**
    1745      * @param object|array $item
     1762     * Handles the checkbox column output.
     1763     *
     1764     * @since 4.2.0
     1765     *
     1766     * @param object|array $item The current item.
    17461767     */
    17471768    protected function column_cb( $item ) {}

  • trunk/src/wp-admin/includes/class-wp-plugins-list-table.php

    r61695 r62491  
    2828     * Constructor.
    2929     *
    30      * @since 3.1.0
     30     * @since 3.2.0
    3131     *
    3232     * @see WP_List_Table::__construct() for more information on default arguments.
    … …  
    6464
    6565    /**
    66      * @return array
     66     * Gets the CSS classes for the list table element.
     67     *
     68     * @since 3.1.0
     69     *
     70     * @return string[] Array of CSS classes for the table tag.
    6771     */
    6872    protected function get_table_classes() {
    … …  
    7175
    7276    /**
    73      * @return bool
     77     * Checks whether the current user can activate plugins for this screen.
     78     *
     79     * @since 3.1.0
     80     *
     81     * @return bool Whether the current user can activate plugins.
    7482     */
    7583    public function ajax_user_can() {
    … …  
    7886
    7987    /**
    80      * @global string $status
    81      * @global array  $plugins
    82      * @global array  $totals
    83      * @global int    $page
    84      * @global string $orderby
    85      * @global string $order
    86      * @global string $s
     88     * Prepares the list of items for displaying.
     89     *
     90     * @since 3.1.0
     91     *
     92     * @global string                                             $status  Current plugin status filter slug.
     93     * @global array<string, array<string, array<string, mixed>>> $plugins Array of plugin data arrays grouped by status.
     94     * @global array<string, int>                                 $totals  Count of plugins for each status group.
     95     * @global int                                                $page    Current page number.
     96     * @global string                                             $orderby Column name to sort by.
     97     * @global string                                             $order   Sort direction, 'ASC' or 'DESC'.
     98     * @global string                                             $s       URL-encoded search term.
    8799     */
    88100    public function prepare_items() {
    … …  
    365377
    366378    /**
     379     * Callback to filter plugins by a search term.
     380     *
     381     * @since 3.1.0
     382     *
    367383     * @global string $s URL encoded search term.
    368384     *
    369      * @param array $plugin
    370      * @return bool
     385     * @param array<string, mixed> $plugin Plugin data array to check against the search term.
     386     * @return bool True if the plugin matches the search term, false otherwise.
    371387     */
    372388    public function _search_callback( $plugin ) {
    … …  
    383399
    384400    /**
    385      * @global string $orderby
    386      * @global string $order
    387      * @param array $plugin_a
    388      * @param array $plugin_b
    389      * @return int
     401     * Callback to sort plugins by a given column.
     402     *
     403     * @since 3.1.0
     404     *
     405     * @global string $orderby The column name to sort by.
     406     * @global string $order   The sort direction ('ASC' or 'DESC').
     407     *
     408     * @param array<string, mixed> $plugin_a First plugin data array to compare.
     409     * @param array<string, mixed> $plugin_b Second plugin data array to compare.
     410     * @return int Negative if $plugin_a sorts before $plugin_b, positive if after, 0 if equal.
    390411     */
    391412    public function _order_callback( $plugin_a, $plugin_b ) {
    … …  
    407428
    408429    /**
    409      * @global array $plugins
     430     * Message to be displayed when there are no items.
     431     *
     432     * @since 3.1.0
     433     *
     434     * @global array<string, array<string, array<string, mixed>>> $plugins Array of plugin data arrays grouped by status.
    410435     */
    411436    public function no_items() {
    … …  
    460485
    461486    /**
    462      * @global string $status
    463      *
    464      * @return string[] Array of column titles keyed by their column name.
     487     * Gets the list of columns for this list table.
     488     *
     489     * @since 3.1.0
     490     *
     491     * @global string $status Current plugin status filter slug.
     492     *
     493     * @return array<string, string> An associative array of column titles keyed by their column name.
    465494     */
    466495    public function get_columns() {
    … …  
    481510
    482511    /**
    483      * @return array
     512     * Gets the list of sortable columns for this list table.
     513     *
     514     * @since 3.1.0
     515     *
     516     * @return array<string, array<int, string|bool>|string> An associative array of sortable columns.
    484517     */
    485518    protected function get_sortable_columns() {
    … …  
    488521
    489522    /**
    490      * @global array $totals
    491      * @global string $status
    492      * @return array
     523     * Gets an associative array of status filter links for the views area.
     524     *
     525     * @since 3.1.0
     526     *
     527     * @global array<string, int> $totals Count of plugins for each status group.
     528     * @global string             $status Current plugin status filter slug.
     529     *
     530     * @return array<string, string> An associative array of views.
    493531     */
    494532    protected function get_views() {
    … …  
    617655
    618656    /**
    619      * @global string $status
    620      * @return array
     657     * Gets the available bulk actions for the plugins list table.
     658     *
     659     * @since 3.1.0
     660     *
     661     * @global string $status Current plugin status filter slug.
     662     *
     663     * @return array<string, string> An associative array of bulk actions.
    621664     */
    622665    protected function get_bulk_actions() {
    … …  
    656699
    657700    /**
    658      * @global string $status
    659      * @param string $which
     701     * Displays the bulk actions dropdown.
     702     *
     703     * @since 3.1.0
     704     *
     705     * @global string $status Current plugin status filter slug.
     706     *
     707     * @param string $which The location of the bulk actions: Either 'top' or 'bottom'.
     708     *                      This is designated as optional for backward compatibility.
    660709     */
    661710    public function bulk_actions( $which = '' ) {
    … …  
    670719
    671720    /**
    672      * @global string $status
    673      * @param string $which
     721     * Displays extra table navigation for the plugins list table.
     722     *
     723     * @since 3.1.0
     724     *
     725     * @global string $status Current plugin status filter slug.
     726     *
     727     * @param string $which The location: 'top' or 'bottom'.
    674728     */
    675729    protected function extra_tablenav( $which ) {
    … …  
    701755
    702756    /**
    703      * @return string
     757     * Gets the current action selected from the bulk actions dropdown.
     758     *
     759     * Also handles the 'clear-recent-list' action from the Recently Active plugins screen.
     760     *
     761     * @since 3.1.0
     762     *
     763     * @return string|false The action name. False if no action was selected.
    704764     */
    705765    public function current_action() {
    … …  
    716776     * @since 3.1.0
    717777     *
    718      * @global string $status
     778     * @global string $status Current plugin status filter slug.
    719779     */
    720780    public function display_rows() {
    … …  
    731791
    732792    /**
    733      * @global string $status
    734      * @global int $page
    735      * @global string $s
    736      * @global array $totals
    737      *
    738      * @param array $item
     793     * Generates the markup for a single plugin row.
     794     *
     795     * @since 3.1.0
     796     *
     797     * @global string             $status Current plugin status filter slug.
     798     * @global int                $page   Current page number.
     799     * @global string             $s      URL-encoded search term.
     800     * @global array<string, int> $totals Count of plugins for each status group.
     801     *
     802     * @param array $item The current item. An array containing the plugin file path and plugin data.
     803     * @phpstan-param array{string, array<string, mixed>} $item
    739804     */
    740805    public function single_row( $item ) {
Note: See TracChangeset for help on using the changeset viewer.