Exception docs

Author: AydinHassan

src/Exception/CheckNotApplicableException.php

@@ -7,15 +7,19 @@
 use RuntimeException;
 
 /**
- * Class CheckNotApplicableException
+ * Represents the situation when a workshop developer tries to use a check in an exercise which has
+ * a type not supported by the check.
+ *
  * @package PhpSchool\PhpWorkshop\Exception
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
 class CheckNotApplicableException extends RuntimeException
 {
     /**
-     * @param CheckInterface $check
-     * @param ExerciseInterface $exercise
+     * Static constructor to create an instance from the check & exercise.
+     *
+     * @param CheckInterface $check The check Instance.
+     * @param ExerciseInterface $exercise The exercise Instance.
      * @return static
      */
     public static function fromCheckAndExercise(CheckInterface $check, ExerciseInterface $exercise)

src/Exception/CliRouteNotExistsException.php

@@ -5,14 +5,15 @@
 use RuntimeException;
 
 /**
- * Class CliRouteNotExistsException
+ * Represents the situation where a command is called which does not exist in the framework.
+ *
  * @package PhpSchool\PhpWorkshop\Exception
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
 class CliRouteNotExistsException extends RuntimeException
 {
     /**
-     * @param string $routeName
+     * @param string $routeName The name of the command which was typed.
      */
     public function __construct($routeName)
     {

src/Exception/CodeExecutionException.php

@@ -6,14 +6,17 @@
 use Symfony\Component\Process\Process;
 
 /**
- * Class CodeExecutionException
+ * Represents the situation where some PHP code could not be executed successfully.
+ *
  * @package PhpSchool\PhpWorkshop\Exception
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
 class CodeExecutionException extends RuntimeException
 {
     /**
-     * @param Process $process
+     * Static constructor to create an instance from a failed `Process` instance.
+     *
+     * @param Process $process The `Process` instance which failed.
      * @return static
      */
     public static function fromProcess(Process $process)

src/Exception/ExerciseNotConfiguredException.php

@@ -6,15 +6,19 @@
 use RuntimeException;
 
 /**
- * Class ExerciseNotConfiguredException
+ * Represents the situation where an exercise requires a check but does not implement
+ * the correct interface enforced by the check.
+ *
  * @package PhpSchool\PhpWorkshop\Exception
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
 class ExerciseNotConfiguredException extends RuntimeException
 {
     /**
-     * @param ExerciseInterface $exercise
-     * @param $interface
+     * Static constructor to create an instance from the exercise and interface name.
+     *
+     * @param ExerciseInterface $exercise The exercise instance.
+     * @param $interface The FQCN of the interface.
      * @return static
      */
     public static function missingImplements(ExerciseInterface $exercise, $interface)

src/Exception/InvalidArgumentException.php

@@ -3,13 +3,16 @@
 namespace PhpSchool\PhpWorkshop\Exception;
 
 /**
- * Class InvalidArgumentException
+ * Represents invalid argument exceptions.
+ *
  * @package PhpSchool\PhpWorkshop\Exception
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
 class InvalidArgumentException extends \InvalidArgumentException
 {
     /**
+     * Static constructor to create from the expected type & the actual value.
+     *
      * @param string $expected
      * @param mixed $actual
      * @return static
@@ -26,6 +29,8 @@ public static function typeMisMatch($expected, $actual)
     }
 
     /**
+     * Static constructor to create from when a parameter should be one of a set of allowed values, but was not.
+     *
      * @param string $parameterName
      * @param mixed[] $allowedValues
      * @param mixed $actualValue
@@ -47,7 +52,7 @@ public static function notValidParameter($parameterName, array $allowedValues, $
      * @param $value
      * @return string
      */
-    public static function stringify($value)
+    private static function stringify($value)
     {
         if (is_object($value)) {
             return get_class($value);

src/Exception/MissingArgumentException.php

@@ -5,7 +5,8 @@
 use RuntimeException;
 
 /**
- * Class MissingArgumentException
+ * Represents the situation where a command was called without required parameters.
+ *
  * @package PhpSchool\PhpWorkshop\Exception
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
@@ -17,8 +18,10 @@ class MissingArgumentException extends RuntimeException
     private $missingArguments = [];
 
     /**
-     * @param $commandName
-     * @param array $missingArguments
+     * Create the exception, requires the command name and missing arguments.
+     *
+     * @param string $commandName The command name.
+     * @param array $missingArguments An array of missing arguments (strings)
      */
     public function __construct($commandName, array $missingArguments)
     {
@@ -33,6 +36,8 @@ public function __construct($commandName, array $missingArguments)
     }
 
     /**
+     * Retrieve the list of missing arguments.
+     *
      * @return array
      */
     public function getMissingArguments()

src/Exception/SolutionExecutionException.php

@@ -5,7 +5,8 @@
 use RuntimeException;
 
 /**
- * Class SolutionExecutionException
+ * Represents the situation where a reference solution cannot be executed (this should only really happen during
+ * workshop development).
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
 class SolutionExecutionException extends RuntimeException