From ab1f87c060b3b5e2da2efe19b44353324b60eda4 Mon Sep 17 00:00:00 2001
From: mmorris <mmorris@tombras.com>
Date: Mon, 27 Apr 2015 10:46:19 -0400
Subject: [PATCH] code standards pass.

---
 core/lib/Drupal/Component/Fault/Assertion.php      | 22 +++-------
 .../Drupal/Component/Fault/AssertionHandler.php    | 12 +++---
 .../Drupal/Component/Fault/BaseFaultHandler.php    | 50 +++++++++-------------
 core/lib/Drupal/Component/Fault/FaultSetup.php     |  9 +---
 .../simpletest/src/AssertionTestingTrait.php       | 10 +----
 core/tests/Drupal/Tests/AssertionException.php     |  2 +-
 core/tests/Drupal/Tests/AssertionTestingTrait.php  |  2 -
 .../Drupal/Tests/BaseAssertionTestingTrait.php     | 29 ++++++-------
 .../Tests/Component/Fault/AssertionHandlerTest.php |  7 +--
 .../Drupal/Tests/Component/Fault/AssertionTest.php |  8 ++--
 .../Tests/Component/Fault/FaultSetupTest.php       | 10 -----
 core/tests/Drupal/Tests/ToStringMock.php           |  2 +-
 12 files changed, 57 insertions(+), 106 deletions(-)

diff --git a/core/lib/Drupal/Component/Fault/Assertion.php b/core/lib/Drupal/Component/Fault/Assertion.php
index 1616ac0..2fbcc7d 100644
--- a/core/lib/Drupal/Component/Fault/Assertion.php
+++ b/core/lib/Drupal/Component/Fault/Assertion.php
@@ -2,8 +2,6 @@
 /**
  * @file
  * Contains \Drupal\Component\Fault\Assertion.
- *
- * A collection of methods to assist the assert statement.
  */
 
 namespace Drupal\Component\Fault;
@@ -11,7 +9,7 @@
 use Traversable;
 
 /**
- * Assertion.
+ * Collection of methods to assist the assert statement.
  *
  * This is a static function hive for use by the assert statement on the more
  * complicated assertions we which to make.
@@ -42,41 +40,33 @@ public static function validCaller($scope = NULL, $trace = []) {
       $trace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS);
     }
 
-    // First level is the function debug_backtrace was called from. Drop.
+    // Prepare trace for analysis.
     array_shift($trace);
 
-    // The second should be assert. If it isn't pitch an error.
     if ($trace[0]['function'] !== 'assert') {
       throw new FaultException('You must call this function from assert()');
     }
 
-    // Now pitch it out.
     array_shift($trace);
 
-    // Idiot Proof.
     if (count($trace) === 0) {
-      throw new FaultException('Why are you asserting this in the global namespace???');
+      throw new FaultException('No caller exists.');
     }
 
-    // Get this level.
+    // Do the analysis.
     $origin = array_shift($trace);
 
-    // Now to find the true origin of the call we have to traverse any
-    // override functions by the children. We'll know when we've hit the caller
-    // because the function name will change.
     do {
       $frame = array_shift($trace);
-    } while ($frame['function'] === $origin['function']);
+    }
+    while ($frame['function'] === $origin['function']);
 
-    // Resolve the namespace of the callee's frame.
     $namespace = substr($origin['class'], 0, strrpos($origin['class'], '\\'));
 
-    // Be a little forgiving of devs who start the scope with a \
     if ($scope && strpos($scope, '\\') === 0) {
       $scope = substr($scope, 1);
     }
 
-    // Now do the check.
     return strpos($frame['class'], empty($scope) ? $namespace : $scope) === 0 ||
         strpos($frame['class'] . '\\' . $frame['function'], empty($scope) ? $namespace : $scope) === 0;
   }
diff --git a/core/lib/Drupal/Component/Fault/AssertionHandler.php b/core/lib/Drupal/Component/Fault/AssertionHandler.php
index a9021d8..5530c80 100644
--- a/core/lib/Drupal/Component/Fault/AssertionHandler.php
+++ b/core/lib/Drupal/Component/Fault/AssertionHandler.php
@@ -54,11 +54,11 @@ protected function verboseResponse() {
     efficiency it is imperative that you encapsulate the expression in a string
     to be evaluated by assert rather than passing an expression to it.
   <?php
-endif ?>
+endif; ?>
   <p><strong>Comment: </strong><?php echo $this->message; ?></p>
   <?php if ($this->reference['error']) :
 ?>
-  <p><strong>Reference: </strong><?php echo $this->reference['error'] ?></p>
+  <p><strong>Reference: </strong><?php echo $this->reference['error']; ?></p>
   <?php
 endif; ?>
   <hr>
@@ -91,13 +91,13 @@ protected function verboseResponse() {
 endif; ?>
   <hr>
   <h2>Stack Trace</h2>
-  <?php if (function_exists('dump') && !isset($_SERVER['DRUPAL_FAULT_COMPONENT_IN_TEST_MODE'])) :
+  <?php if (function_exists('dump')) :
 ?>
   <?php dump($this->trace); ?>
   <?php else :
-    foreach ($this->trace as &$level) {
-    unset($level['args']);
-    }
+    foreach ($this->trace as &$level) :
+      unset($level['args']);
+    endforeach;
     var_dump($this->trace);
 endif; ?>
 </body>
diff --git a/core/lib/Drupal/Component/Fault/BaseFaultHandler.php b/core/lib/Drupal/Component/Fault/BaseFaultHandler.php
index 5609c3c..179a6d9 100644
--- a/core/lib/Drupal/Component/Fault/BaseFaultHandler.php
+++ b/core/lib/Drupal/Component/Fault/BaseFaultHandler.php
@@ -29,11 +29,15 @@
 
   /**
    * Filesystem root for Drupal.
+   *
+   * @var string
    */
   protected $root;
 
   /**
    * Location of the fault.
+   *
+   * @var array
    */
   protected $errorLocation = [
     'file' => '',
@@ -44,6 +48,8 @@
 
   /**
    * Reference information for the fault.
+   *
+   * @var array
    */
   protected $reference = [
     'error' => '',
@@ -53,16 +59,22 @@
 
   /**
    * Fault code.
+   *
+   * @var string
    */
   protected $code;
 
   /**
    * Fault message.
+   *
+   * @var string
    */
   protected $message;
 
   /**
    * Fault backtrace.
+   *
+   * @var array
    */
   protected $trace;
 
@@ -83,7 +95,7 @@
    * the three possible.
    */
   public function __construct($file, $line, $code, $message, $trace, $option = NULL) {
-    // Remember that raising an assertion while evaluating an assertion will
+    // Raising an assertion while evaluating an assertion will
     // cause a segmentation fault in the PHP engine.  This assertion however
     // cannot be fulfilled by a call under that circumstance UNLESS invoked
     // by a handle function other than the one in FaultSetup.
@@ -95,68 +107,52 @@ public function __construct($file, $line, $code, $message, $trace, $option = NUL
     // Remove the root from the error file string to reduce verbosity. There is
     // no security advantage in doing this.
     $this->errorLocation['file'] = substr($file, strlen($this->root));
-
-    // This maps straightforwardly.
     $this->errorLocation['line'] = $line;
 
     // For assertions 'code' means the PHP string of code that evaluated to
     // 'false' and triggered the assert failure. For errors and exceptions this
     // is an error code with an associated PHP constant such as E_ERROR.
     $this->code = $code;
-
-    // Parse out the trace to find the class and method location of the
-    // fault and remove the section of the trace from this namespace.
     $this->parseTrace($trace, $file, $line);
-
-    // Now break down the error message string, extracting any reference link
-    // that it might contain at its start.
     $this->parseMessage($message);
 
   }
 
   /**
-   * Parse out any link at the start of the message.
+   * Parses out any link at the start of the message.
+   *
+   * Break down the error message string, extracting any reference link that it
+   * might contain at its start.
    */
   protected function parseMessage($message) {
-
-    // First look for http which indicates the author of the fault throw has
-    // a page in mind to show explaining what's going on - this will occur for
-    // third party modules.
     if (strpos($message, 'http') === 0) {
       $this->reference['error'] = substr($message, 0, strpos($message, ' '));
       $this->message = substr($message, strpos($message, ' ') + 1);
     }
-    // API: which is shorthand for the online api reference.
     elseif (strpos($message, 'api://') === 0) {
       $this->reference['error'] = str_replace('api://', static::API, substr($message, 0, strpos($message, ' ')));
       $this->message = substr($message, strpos($message, ' ') + 1);
     }
-    // node: which is shorthand for a drupal issue node.
     elseif (strpos($message, 'node://') === 0) {
       $this->reference['error'] = str_replace('node://', 'http://www.drupal.org/node/', substr($message, 0, strpos($message, ' ')));
       $this->message = substr($message, strpos($message, ' ') + 1);
     }
-    // At this point we presume that there is no error link to present, so pass
-    // along whatever message we got.
     else {
       $this->message = $message;
     }
   }
 
   /**
-   * Make sure the backtrace starts from the class and method of the fault.
+   * Parse out the trace to find the class and method location of the fault.
    */
   protected function parseTrace(array $trace, $file, $line) {
 
-    // Traverse the stack until we find the error point.
-    // Works with assertion, need to test for exceptions and errors.
     while ($frame = array_shift($trace)) {
       if (isset($frame['file']) && isset($frame['line']) && $frame['file'] === $file && $frame['line'] === $line) {
         break;
       }
     }
 
-    // Now set the pointers to the class and method of the fault.
     if (count($trace) > 0) {
       if (isset($trace[0]['class'])) {
         $this->errorLocation['class'] = $trace[0]['class'];
@@ -164,18 +160,15 @@ protected function parseTrace(array $trace, $file, $line) {
       $this->errorLocation['method'] = $trace[0]['function'];
     }
 
-    // Assemble the path to the API page for the class and method of the fault.
     if ($this->errorLocation['class']) {
       $this->reference['class'] = $this->getApiPageForClass($this->errorLocation['file'], $this->errorLocation['class']);
       $this->reference['method'] = $this->getApiPageForMethod($this->errorLocation['file'], $this->errorLocation['class'], $this->errorLocation['method']);
     }
-    // Or just the method.
     else {
       $this->reference['method'] = $this->getApiPageForFunction($file, $function);
     }
 
     $this->trace = $trace;
-
   }
 
   /**
@@ -289,7 +282,7 @@ protected function htmlRespond() {
   }
 
   /**
-   * A quiet response.
+   * Send a quiet response.
    */
   protected function quietResponse() {
 
@@ -306,7 +299,7 @@ protected function quietResponse() {
   }
 
   /**
-   * The start of an HTML response.
+   * Print the start of an HTML response.
    */
   protected function printHtmlStart() {
     echo <<<HTML
@@ -352,10 +345,7 @@ protected function sendHeaders($type) {
     // Somewhat redundant - browsers shouldn't cache 500 class responses anyway.
     header("Cache-Control: no-cache, must-revalidate");
     header("Expires: Sat, 26 Jul 1997 05:00:00 GMT");
-
-    // Status return.
     header($_SERVER["SERVER_PROTOCOL"] . " 503 Service Unavailable");
-
   }
 
 }
diff --git a/core/lib/Drupal/Component/Fault/FaultSetup.php b/core/lib/Drupal/Component/Fault/FaultSetup.php
index fd8f79a..2c282aa 100644
--- a/core/lib/Drupal/Component/Fault/FaultSetup.php
+++ b/core/lib/Drupal/Component/Fault/FaultSetup.php
@@ -12,19 +12,12 @@
 class FaultSetup {
 
   /**
-   * Load the environment variables and configure the assertion handler.
-   *
-   * Note that you may call this function at any time to re-register the
-   * Fault System handlers.
+   * Sets Assert Handler when ASSERT_ACTIVE is set.
    */
   public final static function start() {
     if (assert_options(ASSERT_ACTIVE)) {
-      // Register our handler (next method).
       assert_options(ASSERT_CALLBACK, [__CLASS__, 'handleAssert']);
-      // Now set assertions to not be converted to warning errors.
       assert_options(ASSERT_WARNING, 0);
-      // Finally set the script to terminate on assertion failure, forcing
-      // whatever assertion failure that occured to be fixed.
       assert_options(ASSERT_BAIL, 1);
     }
   }
diff --git a/core/modules/simpletest/src/AssertionTestingTrait.php b/core/modules/simpletest/src/AssertionTestingTrait.php
index 6e83811..003e17d 100644
--- a/core/modules/simpletest/src/AssertionTestingTrait.php
+++ b/core/modules/simpletest/src/AssertionTestingTrait.php
@@ -34,11 +34,7 @@
 trait AssertionTestingTrait {
   use BaseAssertionTestingTrait;
   /**
-   * Check if the assertions specified where raised.
-   *
-   * This function can be overloaded. Assertions should be passed in the order
-   * they are expected to occur. After being accounted for the assertion count
-   * is reset.
+   * {@inheritdoc}
    */
   protected function assertAssertionsRaised() {
     $this->assertIdentical(func_get_args(), $this->assertionsRaised, 'Expected Assertions Raised.');
@@ -46,9 +42,7 @@ protected function assertAssertionsRaised() {
   }
 
   /**
-   * Insure no assertions where thrown.
-   *
-   * Called during teardown, but you may wish to call it at other times.
+   * {@inheritdoc}
    */
   protected function assertAssertionNotRaised() {
     $this->assertTrue(count($this->assertionsRaised) === 0, 'No Assertions Raised');
diff --git a/core/tests/Drupal/Tests/AssertionException.php b/core/tests/Drupal/Tests/AssertionException.php
index a809a04..837f11c 100644
--- a/core/tests/Drupal/Tests/AssertionException.php
+++ b/core/tests/Drupal/Tests/AssertionException.php
@@ -7,7 +7,7 @@
 namespace Drupal\Tests;
 
 /**
- * On occassion we need to die immediately on assertion failure.
+ * Assert Fail Exception.
  *
  * In development we die immediately on assertion failure. In most of the tests
  * we allow the test to continue despite the failure to check to see if the code
diff --git a/core/tests/Drupal/Tests/AssertionTestingTrait.php b/core/tests/Drupal/Tests/AssertionTestingTrait.php
index e944385..37e7b51 100644
--- a/core/tests/Drupal/Tests/AssertionTestingTrait.php
+++ b/core/tests/Drupal/Tests/AssertionTestingTrait.php
@@ -30,9 +30,7 @@
    * need to alias this function when you bind in the trait.
    */
   protected function tearDown() {
-
     $this->stopAssertionHandling();
-
     $this->assertEmpty(
             $this->assertionsRaised,
             'Unaccounted for assert fails found at test conclusion: ' . implode(', ', $this->assertionsRaised)
diff --git a/core/tests/Drupal/Tests/BaseAssertionTestingTrait.php b/core/tests/Drupal/Tests/BaseAssertionTestingTrait.php
index 14f267e..10f20d9 100644
--- a/core/tests/Drupal/Tests/BaseAssertionTestingTrait.php
+++ b/core/tests/Drupal/Tests/BaseAssertionTestingTrait.php
@@ -7,10 +7,9 @@
 namespace Drupal\Tests;
 
 /**
- * Methods for testing the internal PHP assert function.
- *
- * This class contains the methods PHP Unit and Simple Test can safely share.
+ * Methods for testing calls to the internal PHP assert function.
  *
+ * This trait contains the methods PHP Unit and Simple Test can safely share.
  * By default, both convert assert failures to exceptions stopping the code in
  * its tracks.  These methods allow the tester to log the last assertion
  * statement's message and thereby monitor when they are thrown and correct.
@@ -19,19 +18,26 @@
 
   /**
    * Flag assertion handler to throw an exception on raise, ending the test.
+   *
+   * @var bool
    */
   protected $dieOnRaise = FALSE;
 
   /**
    * Collections of captured assertions.
+   *
+   * @var array
    */
   protected $assertionsRaised = [];
 
   /**
    * Errors Expected.
    *
-   * This flag prevents the tearDown from checking for unaccounted assertions.
-   * after an error throw.
+   * This flag escapes the check for unaccounted assertions. If an error occurs
+   * any assertions raised before it will be unaccounted for, so we can't check
+   * for them during tear down.
+   *
+   * @var bool
    */
   protected $thereWillBeErrors = FALSE;
 
@@ -59,8 +65,6 @@ public function assertCallbackHandle($file, $line, $code, $message) {
     }
 
     // Otherwise we log the assertion as thrown and let the code continue.
-    // However, be aware we assert that this array is empty during tear down.
-    // If it isn't the test will fail.
     $this->assertionsRaised[] = $message;
 
     // Inform PHP we've successfully completed our handling of the assert fail.
@@ -71,7 +75,6 @@ public function assertCallbackHandle($file, $line, $code, $message) {
    * Start assertion handling for the test.
    */
   protected function startAssertionHandling() {
-
     assert_options(ASSERT_WARNING, FALSE);
     assert_options(ASSERT_BAIL, FALSE);
     assert_options(ASSERT_CALLBACK, [$this, 'assertCallbackHandle']);
@@ -83,7 +86,6 @@ protected function startAssertionHandling() {
    * Suspend assertion handling.
    */
   protected function suspendAssertionHandling() {
-
     assert_options(ASSERT_WARNING, TRUE);
     assert_options(ASSERT_CALLBACK, NULL);
     $this->assertionsRaised = [];
@@ -95,14 +97,9 @@ protected function suspendAssertionHandling() {
    * Call this from tearDown()
    */
   protected function stopAssertionHandling() {
-
     // If an error was expected and indeed thrown there will be no chance to
-    // clear out the assertion log before we reach this function, so set the
-    // flag to skip the assertions check.
-    //
-    // Only use this when testing errors that you are raising yourself with
-    // trigger error (and that itself should be rare).  In other cases go ahead
-    // and catch the assertion by setting the dieOnRaise flag.
+    // clear out the assertion log before we reach this function. In order for
+    // those tests to work set a flag.
     if ($this->thereWillBeErrors) {
       $this->assertionsRaised = [];
       $this->thereWillBeErrors = FALSE;
diff --git a/core/tests/Drupal/Tests/Component/Fault/AssertionHandlerTest.php b/core/tests/Drupal/Tests/Component/Fault/AssertionHandlerTest.php
index 35991d8..78fc25f 100644
--- a/core/tests/Drupal/Tests/Component/Fault/AssertionHandlerTest.php
+++ b/core/tests/Drupal/Tests/Component/Fault/AssertionHandlerTest.php
@@ -27,9 +27,11 @@ public function setUp() {
   }
 
   /**
-   * Test the constructor to make sure it asserts it shouldn't be called.
+   * Test the assert handler.
+   *
+   * The json response mode is used since it's output is easiest to check.
    */
-  public function testConstructor() {
+  public function testAssertHandling() {
     // Flag to the AssertionHandler that it is to spit out HTML anyway, leave
     // the buffers alone, and not log anything.
     $_SERVER['DRUPAL_FAULT_COMPONENT_IN_TEST_MODE'] = TRUE;
@@ -58,7 +60,6 @@ public function testConstructor() {
     $this->assertEquals('Assert Failure line 42 in file /core/tests/Drupal/Tests/Component/Fault/AssertionHandlerTest.php -- asserted: FALSE -- comment: test2',
       ob_get_clean()
     );
-
   }
 
 }
diff --git a/core/tests/Drupal/Tests/Component/Fault/AssertionTest.php b/core/tests/Drupal/Tests/Component/Fault/AssertionTest.php
index 4242aa7..db765ae 100644
--- a/core/tests/Drupal/Tests/Component/Fault/AssertionTest.php
+++ b/core/tests/Drupal/Tests/Component/Fault/AssertionTest.php
@@ -15,7 +15,7 @@
 /**
  * Test the static Assertion assisting Library.
  *
- * @coversDefaultClass \Drupal\Component\Fault\FaultSetup
+ * @coversDefaultClass \Drupal\Component\Fault\Assertion
  *
  * @group Fault
  */
@@ -36,11 +36,11 @@ public function testValidCallerExceptionFromAssert() {
   }
 
   /**
-   * Test the throw of an error when the assert is made outside of any function.
+   * Test no Caller exists situation.
    *
    * @expectedException \Drupal\Component\Fault\FaultException
    *
-   * @expectedExceptionMessage Why are you asserting this in the global namespace???
+   * @expectedExceptionMessage No caller exists.
    */
   public function testValidCallerExceptionNotGlobal() {
     Assertion::validCaller('', [
@@ -161,7 +161,6 @@ public function testValidCallerAnalysis() {
         ['function' => 'caller', 'class' => 'A\\F\\G']
       ])
     );
-
   }
 
   /**
@@ -240,7 +239,6 @@ public function testCollectionOfStrings() {
       1,
       new ToStringMock('doo')
     ])));
-
   }
 
 }
diff --git a/core/tests/Drupal/Tests/Component/Fault/FaultSetupTest.php b/core/tests/Drupal/Tests/Component/Fault/FaultSetupTest.php
index 30aea68..be39e46 100644
--- a/core/tests/Drupal/Tests/Component/Fault/FaultSetupTest.php
+++ b/core/tests/Drupal/Tests/Component/Fault/FaultSetupTest.php
@@ -8,7 +8,6 @@
 
 use Drupal\Component\Fault\FaultSetup;
 use Drupal\Component\Fault\AssertionHandler;
-use Drupal\Tests\AssertionTestingTrait;
 use Drupal\Tests\UnitTestCase;
 
 /**
@@ -16,15 +15,6 @@
  * @group Fault
  */
 class FaultSetupTest extends UnitTestCase {
-  use AssertionTestingTrait;
-
-  /**
-   * {@inheritdoc}
-   */
-  public function setUp() {
-    $this->startAssertionHandling();
-    parent::setUp();
-  }
 
   /**
    * Test the static start method.
diff --git a/core/tests/Drupal/Tests/ToStringMock.php b/core/tests/Drupal/Tests/ToStringMock.php
index eacea64..d1089c1 100644
--- a/core/tests/Drupal/Tests/ToStringMock.php
+++ b/core/tests/Drupal/Tests/ToStringMock.php
@@ -12,7 +12,7 @@
 class ToStringMock {
 
   /**
-   * String.
+   * @var string
    */
   protected $string = '';
 
-- 
1.8.4.2