Merge pull request #120 from php-school/api-docs

Api docs

Author: AydinHassan

composer.json

@@ -53,10 +53,6 @@
         }
     },
     "scripts" : {
-        "test": [
-            "phpunit",
-            "@cs"
-        ],
         "cs" : [
             "phpcs src --standard=PSR2",
             "phpcs test --standard=PSR2"

src/Application.php

@@ -4,16 +4,16 @@
 
 use Assert\Assertion;
 use DI\ContainerBuilder;
-use PhpSchool\PhpWorkshop\Check\CheckInterface;
 use PhpSchool\PhpWorkshop\Check\CheckRepository;
 use PhpSchool\PhpWorkshop\Exception\MissingArgumentException;
 use PhpSchool\PhpWorkshop\Exercise\ExerciseInterface;
 use PhpSchool\PhpWorkshop\Factory\ResultRendererFactory;
 use PhpSchool\PhpWorkshop\Output\OutputInterface;
-use PhpSchool\PhpWorkshop\ResultRenderer\ResultRendererInterface;
 
 /**
- * Class Application
+ * This is the main application class, this takes care of bootstrapping, routing and
+ * output.
+ *
  * @package PhpSchool\PhpWorkshop
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
@@ -45,7 +45,7 @@ final class Application
     private $diConfigFile;
 
     /**
-     * @var string
+     * @var string|null
      */
     private $logo = null;
 
@@ -60,8 +60,11 @@ final class Application
     private $bgColour = 'black';
 
     /**
-     * @param string $workshopTitle
-     * @param $diConfigFile
+     * It should be instantiated with the title of
+     * the workshop and the path to the DI configuration file.
+     *
+     * @param string $workshopTitle The workshop title - this is used throughout the application
+     * @param string $diConfigFile The absolute path to the DI configuration file
      */
     public function __construct($workshopTitle, $diConfigFile)
     {
@@ -73,15 +76,21 @@ public function __construct($workshopTitle, $diConfigFile)
     }
 
     /**
-     * @param string $check
+     * Register a custom check with the application. Exercises will only be able to use the check
+     * if it has been registered here.
+     *
+     * @param string $check The FQCN of the check
      */
     public function addCheck($check)
     {
         $this->checks[] = $check;
     }
 
     /**
-     * @param string $exercise
+     * Register an exercise with the application. Only exercises registered here will
+     * be displayed in the exercise menu.
+     *
+     * @param string $exercise The FQCN of the check
      */
     public function addExercise($exercise)
     {
@@ -104,7 +113,10 @@ public function addResult($resultClass, $resultRendererClass)
     }
 
     /**
-     * @param string $logo
+     * Add an ASCII art logo to the application. This will be displayed at the top of them menu. It will be
+     * automatically padded to sit in the middle.
+     *
+     * @param string $logo The logo
      */
     public function setLogo($logo)
     {
@@ -113,7 +125,10 @@ public function setLogo($logo)
     }
 
     /**
-     * @param string $colour
+     * Modify the foreground color of the workshop menu
+     * Can be any of: black, red, green, yellow, blue, magenta, cyan, white
+     *
+     * @param string $colour The colour
      */
     public function setFgColour($colour)
     {
@@ -122,7 +137,10 @@ public function setFgColour($colour)
     }
 
     /**
-     * @param string $colour
+     * Modify the background color of the workshop menu
+     * Can be any of: black, red, green, yellow, blue, magenta, cyan, white
+     *
+     * @param string $colour The colour
      */
     public function setBgColour($colour)
     {
@@ -131,7 +149,10 @@ public function setBgColour($colour)
     }
 
     /**
-     * Run the app
+     * Executes the framework, invoking the specified command.
+     * The return value is the exit code. 0 for success, anything else is a failure.
+     *
+     * @return int The exit code
      */
     public function run()
     {

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 its 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 solution 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 solution.
+     * @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 student's solution, 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 solution.
+     * @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

@@ -7,16 +7,18 @@
 use PhpSchool\PhpWorkshop\Event\CliExecuteEvent;
 use PhpSchool\PhpWorkshop\Event\Event;
 use PhpSchool\PhpWorkshop\Event\EventDispatcher;
-use PhpSchool\PhpWorkshop\Exercise\ExerciseInterface;
-use PhpSchool\PhpWorkshop\Exercise\ExerciseType;
 use PhpSchool\PhpWorkshop\Exercise\TemporaryDirectoryTrait;
 use PhpSchool\PhpWorkshop\ExerciseCheck\DatabaseExerciseCheck;
 use PhpSchool\PhpWorkshop\Result\Failure;
 use PhpSchool\PhpWorkshop\Result\Success;
 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 +51,7 @@ class DatabaseCheck implements ListenableCheckInterface
     private $solutionDsn;
 
     /**
-     *
+     * Setup paths and DSN's.
      */
     public function __construct()
     {
@@ -71,7 +73,6 @@ public function getName()
     }
 
     /**
-     *
      * @return string
      */
     public function getExerciseInterface()
@@ -80,6 +81,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)