Exercise Check docs

Author: AydinHassan

src/ExerciseCheck/ComposerExerciseCheck.php

@@ -3,13 +3,18 @@
 namespace PhpSchool\PhpWorkshop\ExerciseCheck;
 
 /**
- * Interface ComposerExerciseCheck
+ * This interface should be implemented when you require the check `PhpSchool\PhpWorkshop\Check\ComposerCheck` in your
+ * exercise.
+ *
  * @package PhpSchool\PhpWorkshop\ExerciseCheck
  */
 interface ComposerExerciseCheck
 {
     /**
-     * @return array
+     * Returns an array of composer package names that student's solution should
+     * have required via composer.
+     *
+     * @return array An array of composer package names.
      */
     public function getRequiredPackages();
 }

src/ExerciseCheck/DatabaseExerciseCheck.php

@@ -5,20 +5,30 @@
 use PDO;
 
 /**
- * Interface DatabaseExerciseCheck
+ * This interface should be implemented when you require the check `PhpSchool\PhpWorkshop\Check\DatabaseCheck` in your
+ * exercise.
+ *
  * @package PhpSchool\PhpWorkshop\ExerciseCheck
  */
 interface DatabaseExerciseCheck
 {
     /**
-     * @param PDO $db
-     * @return bool
+     * This method allows your exercise to seed the database *before* the solution's are executed. You can do anything
+     * you normally could with a `PDO` object.
+     *
+     * @param PDO $db A `PDO` instance pointing to the database which will be accessible to the student's solution.
+     * @return void
      */
-    public function verify(PDO $db);
+    public function seed(PDO $db);
 
     /**
-     * @param PDO $db
-     * @return void
+     * This method allows your exercise to verify the state of database *after* the student's solution has been
+     * executed. You can count rows in tables, check for the existence of tables & rows and of course anything else
+     * you can do with a `PDO` object. The method should return a boolean indicating whether the verification
+     * was successful or not.
+     *
+     * @param PDO $db A `PDO` instance pointing to the database which was accessible by the student's solution.
+     * @return bool The result of the verification.
      */
-    public function seed(PDO $db);
+    public function verify(PDO $db);
 }

src/ExerciseCheck/FunctionRequirementsExerciseCheck.php

@@ -3,18 +3,26 @@
 namespace PhpSchool\PhpWorkshop\ExerciseCheck;
 
 /**
- * Interface FunctionRequirementsExerciseCheck
+ * This interface should be implemented when you require the check
+ * `PhpSchool\PhpWorkshop\Check\FunctionRequirementsCheck` in your exercise.
+ *
  * @package PhpSchool\PhpWorkshop\ExerciseCheck
  */
 interface FunctionRequirementsExerciseCheck
 {
     /**
-     * @return string[]
+     * Returns an array of function names that the student's solution should use. The solution
+     * will be parsed and checked for usages of these functions.
+     *
+     * @return string[] An array of function names that *should* be used.
      */
     public function getRequiredFunctions();
 
     /**
-     * @return string[]
+     * Returns an array of function names that the student's solution should not use. The solution
+     * will be parsed and checked for usages of these functions.
+     *
+     * @return string[] An array of function names that *should not* be used.
      */
     public function getBannedFunctions();
 }

src/ExerciseCheck/SelfCheck.php

@@ -5,15 +5,24 @@
 use PhpSchool\PhpWorkshop\Result\ResultInterface;
 
 /**
- * Class SelfCheck
+ * When implemented in an exercise, this interface allows for an exercise to check it's self.
+ * That is, perform additional verifications in the actual exercise class
+ * itself. See [Self Checking Exercises](https://www.phpschool.io/docs/reference/self-checking-exercises) for more
+ * information.
+ *
+ * Self checking runs *after* the student's solution has been run/verified.
+ *
  * @package PhpSchool\PhpWorkshop\ExerciseCheck
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
 interface SelfCheck
 {
     /**
-     * @param string $fileName
-     * @return ResultInterface
+     * The method is passed the absolute file path to the student's solution and should return a result
+     * object which indicates the success or not of the check.
+     *
+     * @param string $fileName The absolute path to the student's submission.
+     * @return ResultInterface The result of the check.
      */
     public function check($fileName);
 }