From 91be8135f3ba23cabdaf71e5a3725801f168eda8 Mon Sep 17 00:00:00 2001 From: Huzaifa Al Mesbah Date: Sun, 30 Nov 2025 19:49:20 +0600 Subject: [PATCH 1/3] Docs: Improve docblocks in WP_Comments_List_Table. Adds missing summary descriptions and improves and tags in to comply with WordPress coding standards. --- .../includes/class-wp-comments-list-table.php | 56 +++++++++++++++---- 1 file changed, 46 insertions(+), 10 deletions(-) diff --git a/src/wp-admin/includes/class-wp-comments-list-table.php b/src/wp-admin/includes/class-wp-comments-list-table.php index 29343f78a0f6d..b074c3804f792 100644 --- a/src/wp-admin/includes/class-wp-comments-list-table.php +++ b/src/wp-admin/includes/class-wp-comments-list-table.php @@ -70,13 +70,17 @@ public function floated_admin_avatar( $name, $comment_id ) { } /** - * @return bool + * Checks if the user can edit posts. + * + * @return bool Whether the user can edit posts. */ public function ajax_user_can() { return current_user_can( 'edit_posts' ); } /** + * Prepares the comments list items. + * * @global string $mode List table view mode. * @global int $post_id * @global string $comment_status @@ -198,8 +202,10 @@ public function prepare_items() { } /** - * @param string $comment_status - * @return int + * Gets the number of comments to display per page. + * + * @param string $comment_status Comment status. + * @return int Comments per page. */ public function get_per_page( $comment_status = 'all' ) { $comments_per_page = $this->get_items_per_page( 'edit_comments_per_page' ); @@ -216,6 +222,8 @@ public function get_per_page( $comment_status = 'all' ) { } /** + * Displays a message when no comments are found. + * * @global string $comment_status */ public function no_items() { @@ -231,9 +239,13 @@ public function no_items() { } /** - * @global int $post_id + * Returns an array of comment status links. + * + * @global int $post_id * @global string $comment_status * @global string $comment_type + * + * @return string[] Array of comment status links. */ protected function get_views() { global $post_id, $comment_status, $comment_type; @@ -354,9 +366,11 @@ protected function get_views() { } /** - * @global string $comment_status + * Gets the available bulk actions for the comments list. * - * @return array + * @global string $comment_status Current comment status filter. + * + * @return array List of bulk action labels keyed by action name. */ protected function get_bulk_actions() { global $comment_status; @@ -395,10 +409,12 @@ protected function get_bulk_actions() { } /** + * Displays extra controls between bulk actions and pagination. + * * @global string $comment_status * @global string $comment_type * - * @param string $which + * @param string $which The location of the extra table nav markup: Either 'top' or 'bottom'. */ protected function extra_tablenav( $which ) { global $comment_status, $comment_type; @@ -453,7 +469,9 @@ protected function extra_tablenav( $which ) { } /** - * @return string|false + * Gets the current action selected from the bulk actions dropdown. + * + * @return string|false Current action or false if none. */ public function current_action() { if ( isset( $_REQUEST['delete_all'] ) || isset( $_REQUEST['delete_all2'] ) ) { @@ -464,6 +482,8 @@ public function current_action() { } /** + * Gets the list of columns. + * * @global int $post_id * * @return string[] Array of column titles keyed by their column name. @@ -547,7 +567,9 @@ protected function comment_type_dropdown( $comment_type ) { } /** - * @return array + * Gets a list of sortable columns. + * + * @return array An associative array containing the sortable columns. */ protected function get_sortable_columns() { return array( @@ -638,10 +660,12 @@ public function display() { } /** + * Generates content for a single row of the table. + * * @global WP_Post $post Global post object. * @global WP_Comment $comment Global comment object. * - * @param WP_Comment $item + * @param WP_Comment $item The comment object. */ public function single_row( $item ) { global $post, $comment; @@ -917,6 +941,8 @@ protected function handle_row_actions( $item, $column_name, $primary ) { } /** + * Outputs the checkbox column. + * * @since 5.9.0 Renamed `$comment` to `$item` to match parent class for PHP 8 named parameter support. * * @param WP_Comment $item The comment object. @@ -941,6 +967,8 @@ public function column_cb( $item ) { } /** + * Outputs the comment column. + * * @param WP_Comment $comment The comment object. */ public function column_comment( $comment ) { @@ -980,6 +1008,8 @@ public function column_comment( $comment ) { } /** + * Outputs the author column. + * * @global string $comment_status * * @param WP_Comment $comment The comment object. @@ -1039,6 +1069,8 @@ public function column_author( $comment ) { } /** + * Outputs the date column. + * * @param WP_Comment $comment The comment object. */ public function column_date( $comment ) { @@ -1067,6 +1099,8 @@ public function column_date( $comment ) { } /** + * Outputs the response column. + * * @param WP_Comment $comment The comment object. */ public function column_response( $comment ) { @@ -1113,6 +1147,8 @@ public function column_response( $comment ) { } /** + * Outputs the default column. + * * @since 5.9.0 Renamed `$comment` to `$item` to match parent class for PHP 8 named parameter support. * * @param WP_Comment $item The comment object. From 5cffcde27a488bee53a45bdc259fce8ae2f626d5 Mon Sep 17 00:00:00 2001 From: Huzaifa Al Mesbah Date: Sun, 30 Nov 2025 20:05:21 +0600 Subject: [PATCH 2/3] Update global variable documentation in comments list --- src/wp-admin/includes/class-wp-comments-list-table.php | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/wp-admin/includes/class-wp-comments-list-table.php b/src/wp-admin/includes/class-wp-comments-list-table.php index b074c3804f792..818a55acbfab8 100644 --- a/src/wp-admin/includes/class-wp-comments-list-table.php +++ b/src/wp-admin/includes/class-wp-comments-list-table.php @@ -81,11 +81,11 @@ public function ajax_user_can() { /** * Prepares the comments list items. * - * @global string $mode List table view mode. - * @global int $post_id - * @global string $comment_status - * @global string $comment_type - * @global string $search + * @global string $mode Current list table display mode. + * @global int $post_id Current post ID filter. + * @global string $comment_status Comment status filter. + * @global string $comment_type Comment type filter. + * @global string $search Search term. */ public function prepare_items() { global $mode, $post_id, $comment_status, $comment_type, $search; From a23453208b02bd64810b4467c07dc425a79c30ca Mon Sep 17 00:00:00 2001 From: Huzaifa Al Mesbah Date: Mon, 1 Dec 2025 11:30:08 +0600 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Weston Ruter --- src/wp-admin/includes/class-wp-comments-list-table.php | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/wp-admin/includes/class-wp-comments-list-table.php b/src/wp-admin/includes/class-wp-comments-list-table.php index 818a55acbfab8..f50dade0d1039 100644 --- a/src/wp-admin/includes/class-wp-comments-list-table.php +++ b/src/wp-admin/includes/class-wp-comments-list-table.php @@ -245,7 +245,7 @@ public function no_items() { * @global string $comment_status * @global string $comment_type * - * @return string[] Array of comment status links. + * @return array Comment status HTML links keyed by view. */ protected function get_views() { global $post_id, $comment_status, $comment_type; @@ -370,7 +370,7 @@ protected function get_views() { * * @global string $comment_status Current comment status filter. * - * @return array List of bulk action labels keyed by action name. + * @return array Bulk action labels keyed by action name. */ protected function get_bulk_actions() { global $comment_status; @@ -569,7 +569,7 @@ protected function comment_type_dropdown( $comment_type ) { /** * Gets a list of sortable columns. * - * @return array An associative array containing the sortable columns. + * @return array The sortable columns. */ protected function get_sortable_columns() { return array(