Docs: Improve docblocks in WP_List_Table and WP_Plugins_List_Table#10989
Docs: Improve docblocks in WP_List_Table and WP_Plugins_List_Table#10989huzaifaalmesbah wants to merge 8 commits intoWordPress:trunkfrom
Conversation
- 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<string, mixed>, array<string, int>, 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
- Improve @var types on all class properties from bare 'array' to precise generics (array<string, mixed>, array<string, string>, 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
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the Core Committers: Use this line as a base for the props when committing in SVN: To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
Test using WordPress PlaygroundThe changes in this pull request can previewed and tested using a WordPress Playground instance. WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser. Some things to be aware of
For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation. |
| * @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. |
There was a problem hiding this comment.
The continuation line (This is designated as optional for backward compatibility.) should be aligned with the @param description for consistency.
There was a problem hiding this comment.
You may want to take a look at the parent class (class-wp-list-table.php) here for reference, as that’s what I’m currently using.
| * | ||
| * @since 3.1.0 | ||
| * | ||
| * @param object|array $item The current item. |
There was a problem hiding this comment.
They object or array will have string keys, yeah?
There was a problem hiding this comment.
They object or array will have
stringkeys, yeah?
Not necessarily. WP_List_Table is an abstract base class that never accesses $item directly; it just passes it through to subclass methods. The actual shape depends on the subclass. core subclasses like WP_Posts_List_Table receive a WP_Post object, while others may use associative arrays. So object|array is intentionally broad to cover both cases.
Co-authored-by: Weston Ruter <westonruter@gmail.com>
There was a problem hiding this comment.
Pull request overview
This PR improves PHPDoc docblocks in WP_List_Table and WP_Plugins_List_Table classes to enhance accuracy, completeness, and consistency with WordPress core documentation standards. The changes add detailed type annotations, improve method descriptions, and add missing @since tags.
Changes:
- Enhanced property type annotations with generic array types (e.g.,
array<string, mixed>) - Improved method docblocks with detailed descriptions and parameter/return types
- Added comprehensive global variable documentation with type annotations
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| src/wp-admin/includes/class-wp-list-table.php | Updated property type annotations to use generic array syntax, added missing @since tags, improved method parameter descriptions, and fixed minor punctuation issues in docblocks |
| src/wp-admin/includes/class-wp-plugins-list-table.php | Added comprehensive method descriptions, detailed parameter and return type documentation, extensive global variable annotations with types, and @since tags for all methods |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| * @global array<string, int> $totals Count of plugins for each status group. | ||
| * | ||
| * @param array $item | ||
| * @param array{string, array<string, mixed>} $item The current item. An array containing the plugin file path and plugin data. |
There was a problem hiding this comment.
The tuple syntax is missing numeric keys. According to PHPDoc standards and WordPress conventions (see wp-includes/pomo/translations.php:300 and wp-includes/php-ai-client/src/Builders/PromptBuilder.php:246), tuple types should specify numeric keys for each element. This should be array{0: string, 1: array<string, mixed>} instead of array{string, array<string, mixed>}.
| * @param array{string, array<string, mixed>} $item The current item. An array containing the plugin file path and plugin data. | |
| * @param array{0: string, 1: array<string, mixed>} $item The current item. An array containing the plugin file path and plugin data. |
There was a problem hiding this comment.
Sure, that's OK. Same result.
…-list-table-docblocks
- 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>
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>
- 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>
There was a problem hiding this comment.
Gemini did some archeology to help find some of the commits where the symbols were introduced:
| Symbol | Version | Introduction Commit |
|---|---|---|
WP_List_Table::__construct() |
3.2.0 | 9730cb8 |
WP_List_Table::$_column_headers |
4.2.0 | 979ba60 |
WP_List_Table::$compat_fields |
4.2.0 | 2742536 |
WP_List_Table::$compat_methods |
4.2.0 | 2742536 |
WP_List_Table::column_default() |
4.2.0 | e3ac341 |
WP_List_Table::column_cb() |
4.2.0 | e3ac341 |
WP_Plugins_List_Table::__construct() |
3.2.0 | 9730cb8 |
There was a problem hiding this comment.
Gemini's archeology of the versions for the symbols in this class:
| Symbol | Version | Introduction Commit |
|---|---|---|
WP_Plugins_List_Table::$show_autoupdates |
5.5.0 | eb79d7f |
WP_Plugins_List_Table::__construct() |
3.2.0 | 9730cb8 |
WP_Plugins_List_Table::get_table_classes() |
3.1.0 | 2394a8d |
WP_Plugins_List_Table::ajax_user_can() |
3.1.0 | 266cd3f |
WP_Plugins_List_Table::prepare_items() |
3.1.0 | 2a7cb74 |
WP_Plugins_List_Table::_search_callback() |
3.1.0 | 2a7cb74 |
WP_Plugins_List_Table::_order_callback() |
3.1.0 | 2a7cb74 |
WP_Plugins_List_Table::no_items() |
3.1.0 | 2a7cb74 |
WP_Plugins_List_Table::search_box() |
4.6.0 | 68cff6a |
WP_Plugins_List_Table::get_columns() |
3.1.0 | 2a7cb74 |
WP_Plugins_List_Table::get_sortable_columns() |
3.1.0 | 2a7cb74 |
WP_Plugins_List_Table::get_views() |
3.1.0 | 2a7cb74 |
WP_Plugins_List_Table::get_bulk_actions() |
3.1.0 | 2a7cb74 |
WP_Plugins_List_Table::bulk_actions() |
3.1.0 | 2a7cb74 |
WP_Plugins_List_Table::extra_tablenav() |
3.1.0 | 2a7cb74 |
WP_Plugins_List_Table::current_action() |
3.1.0 | 2a7cb74 |
WP_Plugins_List_Table::display_rows() |
3.1.0 | 2a7cb74 |
WP_Plugins_List_Table::single_row() |
3.1.0 | a06d068 |
WP_Plugins_List_Table::get_primary_column_name() |
4.3.0 | fa29d5b |
WP_Plugins_List_Table::add_dependents_to_dependency_plugin_row() |
6.5.0 | 2b08a77 |
WP_Plugins_List_Table::add_dependencies_to_dependent_plugin_row() |
6.5.0 | 2b08a77 |
WP_Plugins_List_Table::get_dependency_view_details_link() |
6.5.0 | 2b08a77 |
WP_Plugins_List_Table::get_view_details_link() |
6.5.0 | 2b08a77 |
Ready to proceed with the remaining refinements 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>
This patch improves the PHPDoc docblocks in
WP_List_TableandWP_Plugins_List_Tablefor accuracy, completeness, and consistency with WordPress core documentation standards.Trac: https://core.trac.wordpress.org/ticket/64224