result renderer docs

Author: AydinHassan

src/ResultRenderer/CgiOutResultRenderer.php

@@ -6,10 +6,10 @@
 use PhpSchool\PhpWorkshop\Result\CgiOutResult;
 use PhpSchool\PhpWorkshop\Result\FailureInterface;
 use PhpSchool\PhpWorkshop\Result\ResultInterface;
-use PhpSchool\PhpWorkshop\Result\SuccessInterface;
 
 /**
- * Class CgiOutResultRenderer
+ * Renderer for `PhpSchool\PhpWorkshop\Result\CgiOutResult`.
+ *
  * @package PhpSchool\PhpWorkshop\ResultRenderer
  */
 class CgiOutResultRenderer implements ResultRendererInterface
@@ -21,14 +21,16 @@ class CgiOutResultRenderer implements ResultRendererInterface
     private $result;
 
     /**
-     * @param CgiOutResult $result
+     * @param CgiOutResult $result The result.
      */
     public function __construct(CgiOutResult $result)
     {
         $this->result = $result;
     }
 
     /**
+     * Render the details of each failed request including the mismatching headers and body.
+     *
      * @param ResultsRenderer $renderer
      * @return string
      */

src/ResultRenderer/FailureRenderer.php

@@ -6,7 +6,8 @@
 use PhpSchool\PhpWorkshop\Result\ResultInterface;
 
 /**
- * Class FailureRenderer
+ * Renderer for `PhpSchool\PhpWorkshop\Result\Failure`.
+ *
  * @package PhpSchool\PhpWorkshop\ResultRenderer
  */
 class FailureRenderer implements ResultRendererInterface
@@ -17,14 +18,16 @@ class FailureRenderer implements ResultRendererInterface
     private $result;
 
     /**
-     * @param Failure $result
+     * @param Failure $result The failure.
      */
     public function __construct(Failure $result)
     {
         $this->result = $result;
     }
 
     /**
+     * Simply print the reason.
+     *
      * @param ResultsRenderer $renderer
      * @return string
      */

src/ResultRenderer/FunctionRequirementsFailureRenderer.php

@@ -5,7 +5,8 @@
 use PhpSchool\PhpWorkshop\Result\FunctionRequirementsFailure;
 
 /**
- * Class FunctionRequirementsFailureRenderer
+ * Renderer for `PhpSchool\PhpWorkshop\Result\FunctionRequirementsFailure`.
+ *
  * @package PhpSchool\PhpWorkshop\ResultRenderer
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
@@ -17,14 +18,16 @@ class FunctionRequirementsFailureRenderer implements ResultRendererInterface
     private $result;
 
     /**
-     * @param FunctionRequirementsFailure $result
+     * @param FunctionRequirementsFailure $result The failure.
      */
     public function __construct(FunctionRequirementsFailure $result)
     {
         $this->result = $result;
     }
 
     /**
+     * Print a list of the missing, required functions & print a list of used but banned functions.
+     *
      * @param ResultsRenderer $renderer
      * @return string
      */

src/ResultRenderer/OutputFailureRenderer.php

@@ -6,7 +6,8 @@
 use PhpSchool\PhpWorkshop\Result\StdOutFailure;
 
 /**
- * Class OutputFailureRenderer
+ * Renderer for `PhpSchool\PhpWorkshop\Result\StdOutFailure`.
+ *
  * @package PhpSchool\PhpWorkshop\ResultRenderer
  */
 class OutputFailureRenderer implements ResultRendererInterface
@@ -18,14 +19,16 @@ class OutputFailureRenderer implements ResultRendererInterface
     private $result;
 
     /**
-     * @param StdOutFailure $result
+     * @param StdOutFailure $result The failure.
      */
     public function __construct(StdOutFailure $result)
     {
         $this->result = $result;
     }
 
     /**
+     * Print the actual and expected output.
+     *
      * @param ResultsRenderer $renderer
      * @return string
      */

src/ResultRenderer/ResultRendererInterface.php

@@ -2,18 +2,25 @@
 
 namespace PhpSchool\PhpWorkshop\ResultRenderer;
 
-use PhpSchool\PhpWorkshop\Result\ResultInterface;
-
 /**
- * Interface ResultRendererInterface
+ * The interface, result renderers should adhere to.
+ *
  * @package PhpSchool\PhpWorkshop\ResultRenderer
+ * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
 interface ResultRendererInterface
 {
 
     /**
-     * @param ResultsRenderer $renderer
-     * @return string
+     * This method should return a string representation of the result,
+     * formatted for output on the command line.
+     *
+     * The `PhpSchool\PhpWorkshop\ResultRenderer\ResultsRenderer` method has
+     * various helpers to render line breaks, colour output and can also render child
+     * results.
+     *
+     * @param ResultsRenderer $renderer The main renderer instance.
+     * @return string The string representation of the result.
      */
     public function render(ResultsRenderer $renderer);
 }

src/ResultRenderer/ResultsRenderer.php

@@ -15,7 +15,8 @@
 use PhpSchool\PhpWorkshop\UserState;
 
 /**
- * Class ResultsRenderer
+ * Renderer which renders a `\PhpSchool\PhpWorkshop\ResultAggregator` and writes it the output.
+ *
  * @package PhpSchool\PhpWorkshop\ResultRenderer
  */
 class ResultsRenderer
@@ -51,11 +52,11 @@ class ResultsRenderer
     private $resultRendererFactory;
 
     /**
-     * @param $appName
-     * @param Color $color
-     * @param TerminalInterface $terminal
-     * @param ExerciseRepository $exerciseRepository
-     * @param SyntaxHighlighter $syntaxHighlighter
+     * @param string $appName The name of the binary to run this workshop.
+     * @param Color $color A instance of `Color` used to colour strings with ANSI escape codes.
+     * @param TerminalInterface $terminal A helper to get information regarding the current terminal.
+     * @param ExerciseRepository $exerciseRepository The exercise repository.
+     * @param SyntaxHighlighter $syntaxHighlighter A PHP syntax highlighter for the terminal, uses ANSI escape codes.
      */
     public function __construct(
         $appName,
@@ -74,10 +75,13 @@ public function __construct(
     }
 
     /**
-     * @param ResultAggregator $results
-     * @param ExerciseInterface $exercise
-     * @param UserState $userState
-     * @param OutputInterface $output
+     * Render the result set to the output and statistics on the number of exercises completed and
+     * remaining.
+     *
+     * @param ResultAggregator $results The result set.
+     * @param ExerciseInterface $exercise The exercise instance that was just attempted.
+     * @param UserState $userState The current state of the student's progress.
+     * @param OutputInterface $output The output instance.
      */
     public function render(
         ResultAggregator $results,
@@ -201,8 +205,11 @@ private function styleArray(array $lines, array $styles)
     }
 
     /**
+     * Style/colour a string.
+     * Can be any of: black, red, green, yellow, blue, magenta, cyan, white, bold, italic, underline
+     *
      * @param string $string
-     * @param array|string $colourOrStyle
+     * @param array|string $colourOrStyle A single style as a string or multiple styles as an array.
      *
      * @return string
      *
@@ -222,15 +229,19 @@ public function style($string, $colourOrStyle)
     }
 
     /**
-     * @param ResultInterface $result
-     * @return string
+     * Render a result. Attempt to find the correct renderer via the result renderer factory.
+     *
+     * @param ResultInterface $result The result.
+     * @return string The string representation of the result.
      */
     public function renderResult(ResultInterface $result)
     {
         return $this->resultRendererFactory->create($result)->render($this);
     }
 
     /**
+     * Draw a line break across the terminal.
+     *
      * @return string
      */
     public function lineBreak()