Check docs

Author: AydinHassan

src/Check/CheckInterface.php

@@ -3,7 +3,8 @@
 namespace PhpSchool\PhpWorkshop\Check;
 
 /**
- * Class CheckInterface
+ * Base Interface for Checks.
+ *
  * @package PhpSchool\PhpWorkshop\Comparator
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
@@ -18,7 +19,7 @@ public function getName();
 
     /**
      * This returns the interface the exercise should implement
-     * when requiring this check
+     * when requiring this check. It should be the FQCN of the interface.
      *
      * @return string
      */

src/Check/CheckRepository.php

@@ -2,11 +2,12 @@
 
 namespace PhpSchool\PhpWorkshop\Check;
 
-use PhpSchool\CliMenu\Exception\InvalidTerminalException;
 use PhpSchool\PhpWorkshop\Exception\InvalidArgumentException;
 
 /**
- * Class CheckRepository
+ * This class is the repository containing all the available checks
+ * for the workshop framework.
+ *
  * @package PhpSchool\PhpWorkshop\Check
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
@@ -18,7 +19,7 @@ class CheckRepository
     private $checks = [];
 
     /**
-     * @param CheckInterface[] $checks
+     * @param CheckInterface[] $checks An array of checks available to the workshop framework.
      */
     public function __construct(array $checks = [])
     {
@@ -28,14 +29,18 @@ public function __construct(array $checks = [])
     }
 
     /**
-     * @param CheckInterface $check
+     * Add a new check to the repository.
+     *
+     * @param CheckInterface $check The check instance to add.
      */
     public function registerCheck(CheckInterface $check)
     {
         $this->checks[get_class($check)] = $check;
     }
 
     /**
+     * Get all of the checks in the repository.
+     *
      * @return array
      */
     public function getAll()
@@ -44,9 +49,11 @@ public function getAll()
     }
 
     /**
-     * @param string $class
-     * @return CheckInterface
-     * @throws InvalidArgumentException
+     * Get a check instance via it's class name.
+     *
+     * @param string $class The class name of the check instance.
+     * @return CheckInterface The instance.
+     * @throws InvalidArgumentException If an instance of the check does not exist.
      */
     public function getByClass($class)
     {
@@ -58,6 +65,8 @@ public function getByClass($class)
     }
 
     /**
+     * Query whether a check instance exists in this repository via it's class name.
+     *
      * @param string $class
      * @return bool
      */

src/Check/CodeParseCheck.php

@@ -13,7 +13,9 @@
 use PhpSchool\PhpWorkshop\Result\Success;
 
 /**
- * Class CodeParseCheck
+ * This check attempts to parse a student's solution and returns
+ * a success or failure based on the result of the parsing.
+ *
  * @package PhpSchool\PhpWorkshop\Check
  * @author  Aydin Hassan <aydin@hotmail.co.uk>
  */
@@ -34,6 +36,8 @@ public function __construct(Parser $parser)
     }
 
     /**
+     * Return the check's name
+     *
      * @return string
      */
     public function getName()
@@ -42,9 +46,13 @@ public function getName()
     }
 
     /**
-     * @param ExerciseInterface $exercise
-     * @param string $fileName
-     * @return ResultInterface
+     * This check grabs the contents of the student's submission and
+     * attempts to parse it with `nikic/php-parser`. If any exceptions are thrown
+     * by the parser, it is treated as a failure.
+     *
+     * @param ExerciseInterface $exercise The exercise to check against.
+     * @param string $fileName The absolute path to the student's submission.
+     * @return ResultInterface The result of the check.
      */
     public function check(ExerciseInterface $exercise, $fileName)
     {
@@ -61,6 +69,8 @@ public function check(ExerciseInterface $exercise, $fileName)
     }
 
     /**
+     * This check can run on any exercise type.
+     *
      * @param ExerciseType $exerciseType
      * @return bool
      */
@@ -70,7 +80,6 @@ public function canRun(ExerciseType $exerciseType)
     }
 
     /**
-     *
      * @return string
      */
     public function getExerciseInterface()
@@ -79,6 +88,8 @@ public function getExerciseInterface()
     }
 
     /**
+     * This check should be run before executing the submission, as, if it cannot be parsed
+     * it probably cannot be executed.
      *
      * @return string
      */

src/Check/ComposerCheck.php

@@ -11,13 +11,17 @@
 use PhpSchool\PhpWorkshop\Result\Success;
 
 /**
- * Class ComposerCheck
+ * This check looks for a set of composer packages specified by the exercise
+ * in the students `composer.lock` file.
+ *
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
 class ComposerCheck implements SimpleCheckInterface
 {
 
     /**
+     * Return the check's name
+     *
      * @return string
      */
     public function getName()
@@ -26,9 +30,13 @@ public function getName()
     }
 
     /**
-     * @param ExerciseInterface $exercise
-     * @param string $fileName
-     * @return ResultInterface
+     * This check parses the `composer.lock` file and checks that the student
+     * installed a set of required packages. If they did not a failure is returned, otherwise,
+     * a success is returned.
+     *
+     * @param ExerciseInterface $exercise The exercise to check against.
+     * @param string $fileName The absolute path to the student's submission.
+     * @return ResultInterface The result of the check.
      */
     public function check(ExerciseInterface $exercise, $fileName)
     {
@@ -63,6 +71,8 @@ public function check(ExerciseInterface $exercise, $fileName)
     }
 
     /**
+     * This check can run on any exercise type.
+     *
      * @param ExerciseType $exerciseType
      * @return bool
      */
@@ -81,6 +91,7 @@ public function getExerciseInterface()
     }
 
     /**
+     * This check can run before because if it fails, there is no point executing the solution.
      *
      * @return string
      */

src/Check/DatabaseCheck.php

@@ -16,7 +16,11 @@
 use Symfony\Component\Process\Process;
 
 /**
- * Class DatabaseCheck
+ * This check sets up a database and a `PDO` object. It prepends the database DSN as a CLI argument to the student's
+ * solution so they can connect to the database. The PDO object is passed to the exercise before and after the
+ * student's solution has been executed, allowing you to first seed the database and then verify the contents of the
+ * database.
+ *
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
 class DatabaseCheck implements ListenableCheckInterface
@@ -49,7 +53,7 @@ class DatabaseCheck implements ListenableCheckInterface
     private $solutionDsn;
 
     /**
-     *
+     * Setup paths and DSN's.
      */
     public function __construct()
     {
@@ -71,7 +75,6 @@ public function getName()
     }
 
     /**
-     *
      * @return string
      */
     public function getExerciseInterface()
@@ -80,6 +83,9 @@ public function getExerciseInterface()
     }
 
     /**
+     * Here we attach to various events to seed, verify and inject the DSN's
+     * to the student & reference solution programs's CLI arguments.
+     *
      * @param EventDispatcher $eventDispatcher
      */
     public function attach(EventDispatcher $eventDispatcher)

src/Check/FileExistsCheck.php

@@ -9,13 +9,16 @@
 use PhpSchool\PhpWorkshop\Result\Success;
 
 /**
- * Class FileExistsCheck
+ * This check verifies that the student's solution file actually exists.
+ *
  * @package PhpSchool\PhpWorkshop\Check
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
 class FileExistsCheck implements SimpleCheckInterface
 {
     /**
+     * Return the check's name
+     *
      * @return string
      */
     public function getName()
@@ -24,9 +27,11 @@ public function getName()
     }
 
     /**
-     * @param ExerciseInterface $exercise
-     * @param string $fileName
-     * @return ResultInterface
+     * Simply check that the file exists.
+     *
+     * @param ExerciseInterface $exercise The exercise to check against.
+     * @param string $fileName The absolute path to the student's submission.
+     * @return ResultInterface The result of the check.
      */
     public function check(ExerciseInterface $exercise, $fileName)
     {
@@ -38,6 +43,8 @@ public function check(ExerciseInterface $exercise, $fileName)
     }
 
     /**
+     * This check can run on any exercise type.
+     *
      * @param ExerciseType $exerciseType
      * @return bool
      */
@@ -56,6 +63,7 @@ public function getExerciseInterface()
     }
 
     /**
+     * This check must run before executing the solution becuase it may not exist.
      *
      * @return string
      */

src/Check/FunctionRequirementsCheck.php

@@ -16,7 +16,9 @@
 use PhpSchool\PhpWorkshop\Result\Success;
 
 /**
- * Class FunctionRequirementsCheck
+ * This check verifies that the students submission contains usages of some required functions
+ * and also does not use certain functions (specified by the exercise).
+ *
  * @package PhpSchool\PhpWorkshop\Check
  * @author  Aydin Hassan <aydin@hotmail.co.uk>
  */
@@ -37,6 +39,8 @@ public function __construct(Parser $parser)
     }
 
     /**
+     * Return the check's name
+     *
      * @return string
      */
     public function getName()
@@ -45,9 +49,13 @@ public function getName()
     }
 
     /**
-     * @param ExerciseInterface $exercise
-     * @param string $fileName
-     * @return ResultInterface
+     * Parse the students solution and check that there are usages of
+     * required functions and that banned functions are not used. The requirements
+     * are pulled from the exercise.
+     *
+     * @param ExerciseInterface $exercise The exercise to check against.
+     * @param string $fileName The absolute path to the student's submission.
+     * @return ResultInterface The result of the check.
      */
     public function check(ExerciseInterface $exercise, $fileName)
     {
@@ -92,6 +100,8 @@ public function check(ExerciseInterface $exercise, $fileName)
     }
 
     /**
+     * This check can run on any exercise type.
+     *
      * @param ExerciseType $exerciseType
      * @return bool
      */
@@ -101,7 +111,6 @@ public function canRun(ExerciseType $exerciseType)
     }
 
     /**
-     *
      * @return string
      */
     public function getExerciseInterface()
@@ -110,6 +119,9 @@ public function getExerciseInterface()
     }
 
     /**
+     * This is performed after executing the student's submission because the submission may produce the correct
+     * output, but do it in a way that was not correct for the task. This way the student can see the program works
+     * but missed some requirements.
      *
      * @return string
      */

src/Check/ListenableCheckInterface.php

@@ -12,6 +12,9 @@
 interface ListenableCheckInterface extends CheckInterface
 {
     /**
+     * Attach to events throughout the running/verifying process. Inject verifiers
+     * and listeners.
+     *
      * @param EventDispatcher $eventDispatcher
      */
     public function attach(EventDispatcher $eventDispatcher);