Changeset 56482

Timestamp:

08/28/2023 09:51:44 PM (16 months ago)

Author:

johnbillion

Message:

Privacy: Improve docblocks for hooks and functions related to personal data export and erasure.

See #58833

Location:

trunk/src

Files:

• wp-admin/includes/ajax-actions.php (modified) (4 diffs)
• wp-includes/comment.php (modified) (3 diffs)
• wp-includes/media.php (modified) (1 diff)
• wp-includes/user.php (modified) (1 diff)

trunk/src/wp-admin/includes/ajax-actions.php

@@ -4940 +4940 @@
      *
      *         @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.
@@ -5052 +5052 @@
      * @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.
@@ -5129 +5129 @@
      *         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
@@ -5282 +5282 @@
      * @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.

trunk/src/wp-includes/comment.php

@@ -3685 +3685 @@
  * @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 ) {
@@ -3703 +3703 @@
  *
  * @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 ) {
@@ -3815 +3820 @@
  *
  * @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 ) {

trunk/src/wp-includes/media.php

@@ -5360 +5360 @@
  *
  * @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 ) {

trunk/src/wp-includes/user.php

@@ -3808 +3808 @@
  *
  * @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 ) {