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 3 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>
3 participants
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