Exercise docs

Author: AydinHassan

src/Exercise/AbstractExercise.php

@@ -8,19 +8,29 @@
 use ReflectionClass;
 
 /**
- * Class AbstractExercise
+ * This abstract class implements many of the methods described in `\PhpSchool\PhpWorkshop\Exercise\ExerciseInterface`.
+ * It serves as a good base for an exercise, providing useful defaults for many of the methods.
+ *
  * @package PhpSchool\PhpWorkshop\Exercise
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
 abstract class AbstractExercise
 {
 
     /**
+     * Get the name of the exercise, like `Hello World!`.
+     *
      * @return string
      */
     abstract public function getName();
 
     /**
+     * This returns a single file solution named `solution.php` which
+     * should exist in `workshop-root/exercises/<exercise-name>/solution/`.
+     *
+     * This method can be overwritten if the solution consists of multiple files,
+     * see [Directory Solution](https://www.phpschool.io/docs/reference/exercise-solutions#directory-solution) for more details.
+     *
      * @return SolutionInterface
      */
     public function getSolution()
@@ -37,6 +47,9 @@ public function getSolution()
     }
 
     /**
+     * This returns the problem file path, which is assumed to exist in
+     * `workshop-root/exercises/<exercise-name>/problem/` as a file named `problem.md`.
+     *
      * @return string
      */
     public function getProblem()
@@ -47,7 +60,10 @@ public function getProblem()
     }
 
     /**
-     * @return null
+     * Allows to perform some cleanup after the exercise solution's have been executed, for example
+     * remove files, close DB connections.
+     *
+     * @return void
      */
     public function tearDown()
     {
@@ -63,6 +79,9 @@ private function normaliseName($name)
     }
 
     /**
+     * This method is implemented as empty by default, if you want to add additional checks or listen
+     * to events, you should override this method.
+     *
      * @param ExerciseDispatcher $dispatcher
      */
     public function configure(ExerciseDispatcher $dispatcher)

src/Exercise/CgiExercise.php

@@ -5,13 +5,17 @@
 use Psr\Http\Message\RequestInterface;
 
 /**
- * Interface CgiExercise
+ * This interface describes the additional methods a CGI type exercise should implement.
+ *
  * @package PhpSchool\PhpWorkshop\Exercise
  */
 interface CgiExercise
 {
     /**
-     * @return RequestInterface[]
+     * This method should return an array of PSR-7 requests, which will be forwarded to the student's
+     * solution.
+     *
+     * @return RequestInterface[] An array of PSR-7 requests.
      */
     public function getRequests();
 }

src/Exercise/CliExercise.php

@@ -2,16 +2,18 @@
 
 namespace PhpSchool\PhpWorkshop\Exercise;
 
-use Psr\Http\Message\RequestInterface;
-
 /**
- * Interface CliExercise
+ * This interface describes the additional methods a CLI type exercise should implement.
+ *
  * @package PhpSchool\PhpWorkshop\Exercise
  */
 interface CliExercise
 {
     /**
-     * @return string[]
+     * This method should return an array of strings which will be passed to the student's solution
+     * as command line arguments.
+     *
+     * @return string[] An array of string arguments.
      */
     public function getArgs();
 }

src/Exercise/ExerciseInterface.php

@@ -6,45 +6,64 @@
 use PhpSchool\PhpWorkshop\Solution\SolutionInterface;
 
 /**
- * Class ExerciseInterface
+ * This interface describes all of the methods an exercise
+ * should implement.
+ *
  * @package PhpSchool\PhpWorkshop\Exercise
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
-
 interface ExerciseInterface
 {
 
     /**
+     * Get the name of the exercise, like `Hello World!`.
+     *
      * @return string
      */
     public function getName();
 
     /**
+     * Return the type of exercise. This is an ENUM. See `PhpSchool\PhpWorkshop\Exercise\ExerciseType`.
+     *
      * @return ExerciseType
      */
     public function getType();
 
     /**
+     * This is where the exercise specifies the extra checks it may require. It is also
+     * possible to grab the even dispatcher from the exercise dispatcher and listen to any
+     * events. This method is automatically invoked just before verifying/running an student's solution
+     * to an exercise.
+     *
      * @param ExerciseDispatcher $dispatcher
      */
     public function configure(ExerciseDispatcher $dispatcher);
 
     /**
+     * A short description of the exercise.
+     *
      * @return string
      */
     public function getDescription();
 
     /**
+     * Get the exercise solution.
+     *
      * @return SolutionInterface
      */
     public function getSolution();
 
     /**
+     * Get the absolute path to the markdown file which contains the exercise problem.
+     *
      * @return string
      */
     public function getProblem();
 
     /**
+     * Allows to perform some cleanup after the exercise solution's have been executed, for example
+     * remove files, close DB connections.
+     *
      * @return void
      */
     public function tearDown();

src/Exercise/ExerciseType.php

@@ -7,7 +7,13 @@
 use PhpSchool\PhpWorkshop\ExerciseRunner\CliRunner;
 
 /**
- * Class ExerciseType
+ * This class is a ENUM which represents the types that exercises can be. Instantiation looks like:
+ *
+ * ```php
+ * $typeCli = ExerciseType::CLI();
+ * $typeCgi = ExerciseType::CGI();
+ * ```
+ *
  * @package PhpSchool\PhpWorkshop\Exercise
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */

src/Exercise/SubmissionPatchable.php

@@ -5,13 +5,19 @@
 use PhpSchool\PhpWorkshop\Patch;
 
 /**
- * Interface SubmissionPatchable
+ * This interface, when implemented by an exercise, tells the workshop framework that the exercise
+ * would like to patch the student's submission. This might include adding code to the top of the file like
+ * injecting variables. The exercise should implement the `getPatch()` method and it should return a `Patch`.
+ * See [Patching Exercise Submissions](https://www.phpschool.io/docs/reference/patching-exercise-solutions) for more details.
+ *
  * @package PhpSchool\PhpWorkshop\Exercise
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
 interface SubmissionPatchable
 {
     /**
+     * Get the patch.
+     *
      * @return Patch
      */
     public function getPatch();

src/Exercise/TemporaryDirectoryTrait.php

@@ -3,16 +3,21 @@
 namespace PhpSchool\PhpWorkshop\Exercise;
 
 /**
- * Class TemporaryDirectoryTrait
+ * Helper trait to use in exercises to get a temporary path
+ * for IO stuff.
+ *
  * @package PhpSchool\PhpWorkshop\Exercise
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
 trait TemporaryDirectoryTrait
 {
     /**
-     * @return string
+     * Get a temporary directory to use in exercises, takes in to account
+     * the class-name.
+     *
+     * @return string The absolute path to the temporary directory.
      */
-    protected function getTemporaryPath()
+    public function getTemporaryPath()
     {
         return sprintf(
             '%s/%s',