result docs

Author: AydinHassan

src/Result/CgiOutRequestFailure.php

@@ -5,7 +5,9 @@
 use Psr\Http\Message\RequestInterface;
 
 /**
- * Class CgiOutRequestFailure
+ * A failure result representing the situation where the output of a student's solution did not match the
+ * expected outcome in the context of a HTTP request.
+ *
  * @package PhpSchool\PhpWorkshop\Result
  * @author  Aydin Hassan <aydin@hotmail.co.uk>
  */
@@ -58,6 +60,8 @@ public function __construct(
     }
 
     /**
+     * Get the request object associated with this failure.
+     *
      * @return RequestInterface
      */
     public function getRequest()
@@ -66,6 +70,8 @@ public function getRequest()
     }
 
     /**
+     * Is the output different?
+     *
      * @return bool
      */
     public function bodyDifferent()
@@ -74,6 +80,8 @@ public function bodyDifferent()
     }
 
     /**
+     * Are the headers different?
+     *
      * @return bool
      */
     public function headersDifferent()
@@ -82,6 +90,8 @@ public function headersDifferent()
     }
 
     /**
+     * Are the headers & body different?
+     *
      * @return bool
      */
     public function headersAndBodyDifferent()
@@ -90,6 +100,8 @@ public function headersAndBodyDifferent()
     }
 
     /**
+     * Get the expected output.
+     *
      * @return string
      */
     public function getExpectedOutput()
@@ -98,6 +110,8 @@ public function getExpectedOutput()
     }
 
     /**
+     * Get the actual output.
+     *
      * @return string
      */
     public function getActualOutput()
@@ -106,6 +120,8 @@ public function getActualOutput()
     }
 
     /**
+     * Get the array of expected headers.
+     *
      * @return array
      */
     public function getExpectedHeaders()
@@ -114,6 +130,8 @@ public function getExpectedHeaders()
     }
 
     /**
+     * Get the array of actual headers.
+     *
      * @return array
      */
     public function getActualHeaders()

src/Result/CgiOutResult.php

@@ -2,11 +2,12 @@
 
 namespace PhpSchool\PhpWorkshop\Result;
 
-use PhpSchool\PhpWorkshop\Check\CheckInterface;
 use PhpSchool\PhpWorkshop\ResultAggregator;
 
 /**
- * Class CgiOutFailure
+ * A result which encompasses all the results for each individual request made during
+ * the CGI verification process.
+ *
  * @package PhpSchool\PhpWorkshop\Result
  * @author  Aydin Hassan <aydin@hotmail.co.uk>
  */
@@ -18,8 +19,8 @@ class CgiOutResult extends ResultAggregator implements ResultInterface
     private $name;
 
     /**
-     * @param string $name
-     * @param array $requestResults
+     * @param string $name The name of the check that produced this result.
+     * @param array $requestResults An array of results representing each request.
      */
     public function __construct($name, array $requestResults)
     {
@@ -31,6 +32,8 @@ public function __construct($name, array $requestResults)
 
 
     /**
+     * Get the name of the check that this result was produced from, most likely the CGI Runner.
+     *
      * @return string
      */
     public function getCheckName()

src/Result/Failure.php

@@ -7,7 +7,8 @@
 use PhpSchool\PhpWorkshop\Exception\CodeExecutionException;
 
 /**
- * Class Failure
+ * Default implementation of `PhpSchool\PhpWorkshop\Result\FailureInterface`.
+ *
  * @package PhpSchool\PhpWorkshop
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
@@ -24,8 +25,11 @@ class Failure implements FailureInterface
     private $name;
 
     /**
-     * @param string $name
-     * @param string|null $reason
+     * Create an instance from the name of the check that produces this result
+     * and the reason for the failure.
+     *
+     * @param string $name The name of the check that produced this result.
+     * @param string|null $reason The reason (if any) of the failure.
      */
     public function __construct($name, $reason = null)
     {
@@ -34,40 +38,49 @@ public function __construct($name, $reason = null)
     }
 
     /**
-     * @param string $name
-     * @param $reason
-     * @return static
+     * Named constructor, for added code legibility.
+     *
+     * @param string $name The name of the check that produced this result.
+     * @param string|null $reason The reason (if any) of the failure.
+     * @return static The result.
      */
     public static function fromNameAndReason($name, $reason)
     {
         return new static($name, $reason);
     }
 
     /**
-     * @param CheckInterface $check
-     * @param string $reason
-     * @return static
+     * Static constructor to create from an instance of `PhpSchool\PhpWorkshop\Check\CheckInterface`.
+     *
+     * @param CheckInterface $check The check instance.
+     * @param string $reason The reason (if any) of the failure.
+     * @return static The result.
      */
     public static function fromCheckAndReason(CheckInterface $check, $reason)
     {
         return new static($check->getName(), $reason);
     }
 
     /**
-     * @param string $name
-     * @param CodeExecutionException $e
-     * @return static
+     * Static constructor to create from a `PhpSchool\PhpWorkshop\Exception\CodeExecutionException` exception.
+     *
+     * @param string $name The name of the check that produced this result.
+     * @param CodeExecutionException $e The exception.
+     * @return static The result.
      */
     public static function fromNameAndCodeExecutionFailure($name, CodeExecutionException $e)
     {
         return new static($name, $e->getMessage());
     }
 
     /**
-     * @param CheckInterface $check
-     * @param ParseErrorException $e
-     * @param string $file
-     * @return static
+     * Static constructor to create from a `PhpParser\Error` exception. Many checks will need to parse the student's
+     * solution, so this serves as a helper to create a consistent failure.
+     *
+     * @param CheckInterface $check The check that attempted to parse the solution.
+     * @param ParseErrorException $e The parse exception.
+     * @param string $file The absolute path to the solution.
+     * @return static The result.
      */
     public static function fromCheckAndCodeParseFailure(CheckInterface $check, ParseErrorException $e, $file)
     {
@@ -78,6 +91,8 @@ public static function fromCheckAndCodeParseFailure(CheckInterface $check, Parse
     }
 
     /**
+     * Get the name of the check that this result was produced from.
+     *
      * @return string
      */
     public function getCheckName()
@@ -86,6 +101,8 @@ public function getCheckName()
     }
 
     /**
+     * Get the reason, or `null` if there is no reason.
+     *
      * @return string|null
      */
     public function getReason()

src/Result/FailureInterface.php

@@ -3,7 +3,9 @@
 namespace PhpSchool\PhpWorkshop\Result;
 
 /**
- * Interface FailureInterface
+ * This interface represents a failure. Any result implementing this interface will
+ * be treated as a failure.
+ *
  * @package PhpSchool\PhpWorkshop\Result
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */

src/Result/FunctionRequirementsFailure.php

@@ -5,7 +5,9 @@
 use PhpSchool\PhpWorkshop\Check\CheckInterface;
 
 /**
- * Class FunctionRequirementsFailure
+ * A failure result representing the situation where there were function usage requirements
+ * and they were not met.
+ *
  * @package PhpSchool\PhpWorkshop\Result
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
@@ -24,9 +26,9 @@ class FunctionRequirementsFailure implements FailureInterface
     private $missingFunctions;
 
     /**
-     * @param CheckInterface $check
-     * @param array $bannedFunctions
-     * @param array $missingFunctions
+     * @param CheckInterface $check The check that produced this result.
+     * @param array $bannedFunctions A list of functions that were used, but were banned.
+     * @param array $missingFunctions A list of functions that were not used, but were required.
      */
     public function __construct(CheckInterface $check, array $bannedFunctions, array $missingFunctions)
     {
@@ -36,6 +38,8 @@ public function __construct(CheckInterface $check, array $bannedFunctions, array
     }
 
     /**
+     * Get the list of functions that were used, but were banned.
+     *
      * @return array
      */
     public function getBannedFunctions()
@@ -44,6 +48,8 @@ public function getBannedFunctions()
     }
 
     /**
+     * Get the list of functions that were not used, but were required.
+     *
      * @return array
      */
     public function getMissingFunctions()

src/Result/ResultInterface.php

@@ -3,12 +3,16 @@
 namespace PhpSchool\PhpWorkshop\Result;
 
 /**
- * Interface ResultInterface
+ * The base result interface, on it's own does not mean much, instead the
+ * interfaces `PhpSchool\PhpWorkshop\Result\SuccessInterface` & `PhpSchool\PhpWorkshop\Result\FailureInterface` should be used.
+ *
  * @package PhpSchool\PhpWorkshop\Result
  */
 interface ResultInterface
 {
     /**
+     * Get the name of the check that this result was produced from.
+     *
      * @return string
      */
     public function getCheckName();

src/Result/ResultTrait.php

@@ -5,7 +5,9 @@
 use PhpSchool\PhpWorkshop\Check\CheckInterface;
 
 /**
- * Trait ResultTrait
+ * Helper to proxy the `getCheckName()` method through to the `PhpSchool\PhpWorkshop\Check\CheckInterface`
+ * instance.
+ *
  * @package PhpSchool\PhpWorkshop\Result
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
@@ -17,6 +19,9 @@ trait ResultTrait
     private $check;
 
     /**
+     * Get the check name from the underlying check. Assumes that the `check` property has been
+     * assigned an instance of `PhpSchool\PhpWorkshop\Check\CheckInterface`.
+     *
      * @return string
      */
     public function getCheckName()

src/Result/StdOutFailure.php

@@ -5,7 +5,9 @@
 use PhpSchool\PhpWorkshop\Check\CheckInterface;
 
 /**
- * Class StdOutFailure
+ * A failure result representing the situation where the output of a solution does not match
+ * that of the expected output.
+ *
  * @package PhpSchool\PhpWorkshop\Result
  * @author  Aydin Hassan <aydin@hotmail.co.uk>
  */
@@ -27,9 +29,9 @@ class StdOutFailure implements FailureInterface
     private $actualOutput;
 
     /**
-     * @param string $name
-     * @param string $expectedOutput
-     * @param string $actualOutput
+     * @param string $name The name of the check that produced this result.
+     * @param string $expectedOutput The expected output.
+     * @param string $actualOutput The actual output.
      */
     public function __construct($name, $expectedOutput, $actualOutput)
     {
@@ -39,28 +41,34 @@ public function __construct($name, $expectedOutput, $actualOutput)
     }
 
     /**
-     * @param string $name
-     * @param $expectedOutput
-     * @param $actualOutput
-     * @return static
+     * Named constructor, for added code legibility.
+     *
+     * @param string $name The name of the check that produced this result.
+     * @param string $expectedOutput The expected output.
+     * @param string $actualOutput The actual output.
+     * @return static The result.
      */
     public static function fromNameAndOutput($name, $expectedOutput, $actualOutput)
     {
         return new static($name, $expectedOutput, $actualOutput);
     }
 
     /**
-     * @param CheckInterface $check
-     * @param $expectedOutput
-     * @param $actualOutput
-     * @return static
+     * Static constructor to create from an instance of `PhpSchool\PhpWorkshop\Check\CheckInterface`.
+     *
+     * @param CheckInterface $check The check instance.
+     * @param string $expectedOutput The expected output.
+     * @param string $actualOutput The actual output.
+     * @return static The result.
      */
     public static function fromCheckAndOutput(CheckInterface $check, $expectedOutput, $actualOutput)
     {
         return new static($check->getName(), $expectedOutput, $actualOutput);
     }
 
     /**
+     * Get the name of the check that this result was produced from.
+     *
      * @return string
      */
     public function getCheckName()
@@ -69,6 +77,8 @@ public function getCheckName()
     }
 
     /**
+     * Get the expected output.
+     *
      * @return string
      */
     public function getExpectedOutput()
@@ -77,6 +87,8 @@ public function getExpectedOutput()
     }
 
     /**
+     * Get the actual output.
+     *
      * @return string
      */
     public function getActualOutput()