Command* docs

Author: AydinHassan

src/CommandDefinition.php

@@ -3,7 +3,10 @@
 namespace PhpSchool\PhpWorkshop;
 
 /**
- * Class CommandDefinition
+ * Represents a command in the workshop framework. Simply consists of a
+ * command name, required arguments and either a service name of callable to
+ * execute when the command is run.
+ *
  * @package PhpSchool\PhpWorkshop
  * @author Aydin Hassan <[email protected]>
  */
@@ -15,7 +18,7 @@ class CommandDefinition
     private $name;
 
     /**
-     * @var array
+     * @var string[]
      */
     private $args;
 
@@ -25,11 +28,9 @@ class CommandDefinition
     private $commandCallable;
 
     /**
-     * CommandDefinition constructor.
-     *
-     * @param string $name
-     * @param array $args
-     * @param string|callable $commandCallable
+     * @param string $name The name of the command (this is how the student would invoke the command from the cli)
+     * @param string[] $args A list of required arguments. This must be an array of strings.
+     * @param string|callable $commandCallable The name of a callable container entry or an actual PHP callable.
      */
     public function __construct($name, array $args, $commandCallable)
     {
@@ -39,6 +40,8 @@ public function __construct($name, array $args, $commandCallable)
     }
 
     /**
+     * Get the name of the command
+     *
      * @return string
      */
     public function getName()
@@ -47,6 +50,8 @@ public function getName()
     }
 
     /**
+     * Get the list of required arguments
+     *
      * @return array
      */
     public function getRequiredArgs()
@@ -55,6 +60,8 @@ public function getRequiredArgs()
     }
 
     /**
+     * Get the callable associated with this command
+     *
      * @return string|callable
      */
     public function getCommandCallable()

src/CommandRouter.php

@@ -8,7 +8,10 @@
 use SebastianBergmann\Environment\Runtime;
 
 /**
- * Class CommandRouter
+ * Parses $argv (or passed array) and attempts to find a command
+ * which is suitable for what was typed on the cli. It then executed the callable
+ * associated with that command definition.
+ *
  * @package PhpSchool\PhpWorkshop
  * @author Aydin Hassan <[email protected]>
  */
@@ -26,14 +29,20 @@ class CommandRouter
     private $defaultCommand;
 
     /**
-     * @var \Interop\Container\ContainerInterface
+     * @var ContainerInterface
      */
     private $container;
 
     /**
-     * @param CommandDefinition[] $commands
-     * @param $default
-     * @param \Interop\Container\ContainerInterface $container
+     * Accepts an array of CommandDefinition's which represent the application. Also takes a default
+     * (name of one of the commands) which will be used if the workshop was invoked with no arguments.
+     *
+     * Also accepts an instance of the container so it can look for services in there which may by defined
+     * as the callable for one of the command definitions.
+     *
+     * @param CommandDefinition[] $commands An array of command definitions
+     * @param string $default The default command to use (if the workshop was invoked with no arguments)
+     * @param ContainerInterface $container An instance of the container
      */
     public function __construct(array $commands, $default, ContainerInterface $container)
     {
@@ -61,6 +70,18 @@ private function addCommand(CommandDefinition $c)
     }
 
     /**
+     * Attempts to route the command. Parses $argv (or a given array), extracting the command name and
+     * arguments. Using the command name, the command definition is looked up.
+     *
+     * The number of arguments are validated against the required arguments for the command
+     * (specified by the definition)
+     *
+     * We get the callable from the command definition, or if it is the name of a service, we lookup the service
+     * in the container and validate that it is a callable.
+     *
+     * Finally, the callable is invoked with the arguments passed from the cli. The return value of
+     * callable is returned (if it is an integer, if not zero (success) is returned).
+     *
      * @param array $args
      * @return int
      * @throws CliRouteNotExists