From cd5b7df8b86b16288eb13309cac7150e4a567c42 Mon Sep 17 00:00:00 2001
From: Sergey Biryukov <sergeybiryukov@git.wordpress.org>
Date: Sun, 5 Jan 2020 15:31:10 +0000
Subject: [PATCH] Docs: Improve documentation for
 `tests/phpunit/includes/testcase-ajax.php`.

Props andizer, SergeyBiryukov.
Fixes #47568.

git-svn-id: https://develop.svn.wordpress.org/trunk@47041 602fd350-edb4-49c9-b593-d223f7449a82
---
 tests/phpunit/includes/exceptions.php    | 17 +++----
 tests/phpunit/includes/testcase-ajax.php | 56 ++++++++++++------------
 2 files changed, 38 insertions(+), 35 deletions(-)

diff --git a/tests/phpunit/includes/exceptions.php b/tests/phpunit/includes/exceptions.php
index 50976fb0b3..138c12e18c 100644
--- a/tests/phpunit/includes/exceptions.php
+++ b/tests/phpunit/includes/exceptions.php
@@ -5,13 +5,14 @@ class WP_Tests_Exception extends PHPUnit_Framework_Exception {
 }
 
 /**
- * General exception for wp_die()
+ * General exception for wp_die().
  */
 class WPDieException extends Exception {}
 
 /**
- * Exception for cases of wp_die(), for ajax tests.
- * This means there was an error (no output, and a call to wp_die)
+ * Exception for cases of wp_die(), for Ajax tests.
+ *
+ * This means there was an error (no output, and a call to wp_die).
  *
  * @package    WordPress
  * @subpackage Unit Tests
@@ -20,11 +21,11 @@ class WPDieException extends Exception {}
 class WPAjaxDieStopException extends WPDieException {}
 
 /**
- * Exception for cases of wp_die(), for ajax tests.
- * This means execution of the ajax function should be halted, but the unit
- * test can continue.  The function finished normally and there was not an
- * error (output happened, but wp_die was called to end execution)  This is
- * used with WP_Ajax_Response::send
+ * Exception for cases of wp_die(), for Ajax tests.
+ *
+ * This means the execution of the Ajax function should be halted, but the unit test
+ * can continue. The function finished normally and there was no error (output happened,
+ * but wp_die was called to end execution). This is used with WP_Ajax_Response::send().
  *
  * @package    WordPress
  * @subpackage Unit Tests
diff --git a/tests/phpunit/includes/testcase-ajax.php b/tests/phpunit/includes/testcase-ajax.php
index 736d362f76..ac31782f6b 100644
--- a/tests/phpunit/includes/testcase-ajax.php
+++ b/tests/phpunit/includes/testcase-ajax.php
@@ -1,12 +1,4 @@
 <?php
-/**
- * Ajax test cases
- *
- * @package    WordPress
- * @subpackage UnitTests
- * @since      3.4.0
- */
-
 /**
  * Ajax test case class
  *
@@ -17,14 +9,14 @@
 abstract class WP_Ajax_UnitTestCase extends WP_UnitTestCase {
 
 	/**
-	 * Last AJAX response.  This is set via echo -or- wp_die.
+	 * Last Ajax response. This is set via echo -or- wp_die.
 	 *
 	 * @var string
 	 */
 	protected $_last_response = '';
 
 	/**
-	 * List of ajax actions called via GET
+	 * List of Ajax actions called via GET.
 	 *
 	 * @var array
 	 */
@@ -40,14 +32,14 @@ abstract class WP_Ajax_UnitTestCase extends WP_UnitTestCase {
 	);
 
 	/**
-	 * Saved error reporting level
+	 * Saved error reporting level.
 	 *
 	 * @var int
 	 */
 	protected $_error_level = 0;
 
 	/**
-	 * List of ajax actions called via POST
+	 * List of Ajax actions called via POST.
 	 *
 	 * @var array
 	 */
@@ -139,8 +131,9 @@ abstract class WP_Ajax_UnitTestCase extends WP_UnitTestCase {
 	}
 
 	/**
-	 * Set up the test fixture.
-	 * Override wp_die(), pretend to be ajax, and suppress E_WARNINGs
+	 * Sets up the test fixture.
+	 *
+	 * Overrides wp_die(), pretends to be Ajax, and suppresses E_WARNINGs.
 	 */
 	public function setUp() {
 		parent::setUp();
@@ -162,8 +155,9 @@ abstract class WP_Ajax_UnitTestCase extends WP_UnitTestCase {
 	}
 
 	/**
-	 * Tear down the test fixture.
-	 * Reset $_POST, remove the wp_die() override, restore error reporting
+	 * Tears down the test fixture.
+	 *
+	 * Resets $_POST, removes the wp_die() override, restores error reporting.
 	 */
 	public function tearDown() {
 		parent::tearDown();
@@ -178,7 +172,7 @@ abstract class WP_Ajax_UnitTestCase extends WP_UnitTestCase {
 	}
 
 	/**
-	 * Clear login cookies, unset the current user
+	 * Clears login cookies, unsets the current user.
 	 */
 	public function logout() {
 		unset( $GLOBALS['current_user'] );
@@ -189,7 +183,7 @@ abstract class WP_Ajax_UnitTestCase extends WP_UnitTestCase {
 	}
 
 	/**
-	 * Return our callback handler
+	 * Returns our callback handler
 	 *
 	 * @return callback
 	 */
@@ -198,8 +192,10 @@ abstract class WP_Ajax_UnitTestCase extends WP_UnitTestCase {
 	}
 
 	/**
-	 * Handler for wp_die()
+	 * Handler for wp_die().
+	 *
 	 * Save the output for analysis, stop execution by throwing an exception.
+	 *
 	 * Error conditions (no output, just die) will throw <code>WPAjaxDieStopException( $message )</code>
 	 * You can test for this with:
 	 * <code>
@@ -211,7 +207,11 @@ abstract class WP_Ajax_UnitTestCase extends WP_UnitTestCase {
 	 * $this->setExpectedException( 'WPAjaxDieContinueException', 'something contained in $message' );
 	 * </code>
 	 *
-	 * @param string $message
+	 * @param string $message The message to set.
+	 *
+	 * @throws WPAjaxDieStopException     Thrown to stop further execution.
+	 * @throws WPAjaxDieContinueException Thrown to stop execution of the Ajax function,
+	 *                                    but continue the unit test.
 	 */
 	public function dieHandler( $message ) {
 		$this->_last_response .= ob_get_clean();
@@ -228,10 +228,11 @@ abstract class WP_Ajax_UnitTestCase extends WP_UnitTestCase {
 	}
 
 	/**
-	 * Switch between user roles
-	 * E.g. administrator, editor, author, contributor, subscriber
+	 * Switches between user roles.
 	 *
-	 * @param string $role
+	 * E.g. administrator, editor, author, contributor, subscriber.
+	 *
+	 * @param string $role The role to set.
 	 */
 	protected function _setRole( $role ) {
 		$post    = $_POST;
@@ -241,11 +242,12 @@ abstract class WP_Ajax_UnitTestCase extends WP_UnitTestCase {
 	}
 
 	/**
-	 * Mimic the ajax handling of admin-ajax.php
-	 * Capture the output via output buffering, and if there is any, store
-	 * it in $this->_last_response.
+	 * Mimics the Ajax handling of admin-ajax.php.
 	 *
-	 * @param string $action
+	 * Captures the output via output buffering, and if there is any,
+	 * stores it in $this->_last_response.
+	 *
+	 * @param string $action The action to handle.
 	 */
 	protected function _handleAjax( $action ) {