From 722ce44ead9d1803b55b8cc64b8d30c346f3e9c5 Mon Sep 17 00:00:00 2001
From: Sergey Biryukov <sergeybiryukov@git.wordpress.org>
Date: Tue, 30 Mar 2021 14:22:48 +0000
Subject: [PATCH] Docs: Add documentation for the
 `::setup_export_contents_test` method used in personal data export tests.

Follow-up to [50613].

Props hellofromTonya.
See #51423.

git-svn-id: https://develop.svn.wordpress.org/trunk@50616 602fd350-edb4-49c9-b593-d223f7449a82
---
 ...wpPrivacyGeneratePersonalDataExportFile.php | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/tests/phpunit/tests/privacy/wpPrivacyGeneratePersonalDataExportFile.php b/tests/phpunit/tests/privacy/wpPrivacyGeneratePersonalDataExportFile.php
index 89cb1eeac7..8d5bcbe412 100644
--- a/tests/phpunit/tests/privacy/wpPrivacyGeneratePersonalDataExportFile.php
+++ b/tests/phpunit/tests/privacy/wpPrivacyGeneratePersonalDataExportFile.php
@@ -387,7 +387,20 @@ class Tests_Privacy_WpPrivacyGeneratePersonalDataExportFile extends WP_UnitTestC
 		$this->assertSame( $expected, $actual_json );
 	}
 
+	/**
+	 * Sets up the export contents.
+	 *
+	 * Tasks:
+	 * - Delete or update the '_export_data_grouped' post meta.
+	 * - Run `wp_privacy_generate_personal_data_export_file()`.
+	 * - Unzip the export package in a temporary directory to give the test access to the export files.
+	 *
+	 * @param mixed $export_data_grouped Optional. '_export_data_grouped' post meta value.
+	 *                                   When null, delete the meta; else update to the given value.
+	 * @return string Export report directory path.
+	 */
 	private function setup_export_contents_test( $export_data_grouped = null ) {
+		// Delete or update the given meta.
 		if ( null === $export_data_grouped ) {
 			delete_post_meta( self::$export_request_id, '_export_data_grouped' );
 		} else {
@@ -399,13 +412,14 @@ class Tests_Privacy_WpPrivacyGeneratePersonalDataExportFile extends WP_UnitTestC
 		wp_privacy_generate_personal_data_export_file( self::$export_request_id );
 		$this->assertTrue( file_exists( $this->export_file_name ) );
 
+		// Create a temporary export directory for the test's export files.
 		$report_dir = trailingslashit( self::$exports_dir . 'test_contents' );
 		mkdir( $report_dir );
 
+		// Unzip the current test's export file to give the test access to .html and .json files.
 		$zip        = new ZipArchive();
 		$opened_zip = $zip->open( $this->export_file_name );
 		$this->assertTrue( $opened_zip );
-
 		$zip->extractTo( $report_dir );
 		$zip->close();
 
@@ -413,7 +427,7 @@ class Tests_Privacy_WpPrivacyGeneratePersonalDataExportFile extends WP_UnitTestC
 	}
 
 	/**
-	 * Replace expected content's timestamp placeholder with the actual content's timestamp.
+	 * Replaces expected content's timestamp placeholder with the actual content's timestamp.
 	 *
 	 * Used when the expected content has a placeholder, i.e. used to avoid second time differences
 	 * between the test and code.