From 7c254c5510f6e5227e320ea3118f411504f1fe1a Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Mon, 28 Aug 2023 21:51:44 +0000 Subject: [PATCH] Privacy: Improve docblocks for hooks and functions related to personal data export and erasure. See #58833 git-svn-id: https://develop.svn.wordpress.org/trunk@56482 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-admin/includes/ajax-actions.php | 23 +++++++++++++++-------- src/wp-includes/comment.php | 24 ++++++++++++++++++------ src/wp-includes/media.php | 9 +++++++-- src/wp-includes/user.php | 7 ++++++- 4 files changed, 46 insertions(+), 17 deletions(-) diff --git a/src/wp-admin/includes/ajax-actions.php b/src/wp-admin/includes/ajax-actions.php index 3c5dab31b5..16b827d7bd 100644 --- a/src/wp-admin/includes/ajax-actions.php +++ b/src/wp-admin/includes/ajax-actions.php @@ -4939,8 +4939,8 @@ function wp_ajax_wp_privacy_export_personal_data() { * Array of personal data exporters. * * @type callable $callback Callable exporter function that accepts an - * email address and a page and returns an array - * of name => value pairs of personal data. + * email address and a page number and returns an + * array of name => value pairs of personal data. * @type string $exporter_friendly_name Translated user facing friendly name for the * exporter. * } @@ -5051,10 +5051,10 @@ function wp_ajax_wp_privacy_export_personal_data() { * * @since 4.9.6 * - * @param array $response The personal data for the given exporter and page. + * @param array $response The personal data for the given exporter and page number. * @param int $exporter_index The index of the exporter that provided this data. * @param string $email_address The email address associated with this personal data. - * @param int $page The page for this response. + * @param int $page The page number for this response. * @param int $request_id The privacy request post ID associated with this request. * @param bool $send_as_email Whether the final results of the export should be emailed to the user. * @param string $exporter_key The key (slug) of the exporter that provided this data. @@ -5128,8 +5128,8 @@ function wp_ajax_wp_privacy_erase_personal_data() { * @type array ...$0 { * Array of personal data exporters. * - * @type callable $callback Callable eraser that accepts an email address and - * a page and returns an array with boolean values for + * @type callable $callback Callable eraser that accepts an email address and a page + * number, and returns an array with boolean values for * whether items were removed or retained and any messages * from the eraser, as well as if additional pages are * available. @@ -5281,10 +5281,17 @@ function wp_ajax_wp_privacy_erase_personal_data() { * * @since 4.9.6 * - * @param array $response The personal data for the given exporter and page. + * @param array $response { + * The personal data for the given exporter and page number. + * + * @type bool $items_removed Whether items were actually removed or not. + * @type bool $items_retained Whether items were retained or not. + * @type string[] $messages An array of messages to add to the personal data export file. + * @type bool $done Whether the eraser is finished or not. + * } * @param int $eraser_index The index of the eraser that provided this data. * @param string $email_address The email address associated with this personal data. - * @param int $page The page for this response. + * @param int $page The page number for this response. * @param int $request_id The privacy request post ID associated with this request. * @param string $eraser_key The key (slug) of the eraser that provided this data. */ diff --git a/src/wp-includes/comment.php b/src/wp-includes/comment.php index 604ede7c87..b538b2c5c1 100644 --- a/src/wp-includes/comment.php +++ b/src/wp-includes/comment.php @@ -3684,8 +3684,8 @@ function wp_handle_comment_submission( $comment_data ) { * * @since 4.9.6 * - * @param array $exporters An array of personal data exporters. - * @return array An array of personal data exporters. + * @param array[] $exporters An array of personal data exporters. + * @return array[] An array of personal data exporters. */ function wp_register_comment_personal_data_exporter( $exporters ) { $exporters['wordpress-comments'] = array( @@ -3702,8 +3702,13 @@ function wp_register_comment_personal_data_exporter( $exporters ) { * @since 4.9.6 * * @param string $email_address The comment author email address. - * @param int $page Comment page. - * @return array An array of personal data. + * @param int $page Comment page number. + * @return array { + * An array of personal data. + * + * @type array[] $data An array of personal data arrays. + * @type bool $done Whether the exporter is finished. + * } */ function wp_comments_personal_data_exporter( $email_address, $page = 1 ) { // Limit us to 500 comments at a time to avoid timing out. @@ -3814,8 +3819,15 @@ function wp_register_comment_personal_data_eraser( $erasers ) { * @global wpdb $wpdb WordPress database abstraction object. * * @param string $email_address The comment author email address. - * @param int $page Comment page. - * @return array + * @param int $page Comment page number. + * @return array { + * Data removal results. + * + * @type bool $items_removed Whether items were actually removed. + * @type bool $items_retained Whether items were retained. + * @type string[] $messages An array of messages to add to the personal data export file. + * @type bool $done Whether the eraser is finished. + * } */ function wp_comments_personal_data_eraser( $email_address, $page = 1 ) { global $wpdb; diff --git a/src/wp-includes/media.php b/src/wp-includes/media.php index aeedcc22a9..e037a0608b 100644 --- a/src/wp-includes/media.php +++ b/src/wp-includes/media.php @@ -5359,8 +5359,13 @@ function wp_register_media_personal_data_exporter( $exporters ) { * @since 4.9.6 * * @param string $email_address The attachment owner email address. - * @param int $page Attachment page. - * @return array An array of personal data. + * @param int $page Attachment page number. + * @return array { + * An array of personal data. + * + * @type array[] $data An array of personal data arrays. + * @type bool $done Whether the exporter is finished. + * } */ function wp_media_personal_data_exporter( $email_address, $page = 1 ) { // Limit us to 50 attachments at a time to avoid timing out. diff --git a/src/wp-includes/user.php b/src/wp-includes/user.php index 04e6aab999..5f8fe38071 100644 --- a/src/wp-includes/user.php +++ b/src/wp-includes/user.php @@ -3807,7 +3807,12 @@ function wp_register_user_personal_data_exporter( $exporters ) { * @since 5.4.0 Added 'Session Tokens' group to the export data. * * @param string $email_address The user's email address. - * @return array An array of personal data. + * @return array { + * An array of personal data. + * + * @type array[] $data An array of personal data arrays. + * @type bool $done Whether the exporter is finished. + * } */ function wp_user_personal_data_exporter( $email_address ) { $email_address = trim( $email_address );