From ad357234363ab82a805b2c83852359a1c6979353 Mon Sep 17 00:00:00 2001
From: Kuba <jakub@keios.eu>
Date: Fri, 12 Aug 2016 12:04:56 +0200
Subject: [PATCH 1/2] code inspection and cleanup

---
 src/Contracts/Runnable.php      |  1 -
 src/Core/Dispatcher.php         |  5 ++---
 src/Core/Event.php              |  1 +
 src/Core/Scenario.php           | 13 +++++++++++++
 src/Core/ScenarioFactory.php    |  7 +++----
 src/Core/ScenarioRepository.php |  2 ++
 src/Core/ScenarioStepsList.php  | 14 +++++++++++++-
 7 files changed, 34 insertions(+), 9 deletions(-)

diff --git a/src/Contracts/Runnable.php b/src/Contracts/Runnable.php
index 367edc9..1bcc0ab 100644
--- a/src/Contracts/Runnable.php
+++ b/src/Contracts/Runnable.php
@@ -1,7 +1,6 @@
 <?php namespace Keios\Apparatus\Contracts;
 
 use Keios\Apparatus\Core\Dispatcher;
-use Keios\Apparatus\Core\Step;
 
 interface Runnable
 {
diff --git a/src/Core/Dispatcher.php b/src/Core/Dispatcher.php
index a4aade9..acb72eb 100644
--- a/src/Core/Dispatcher.php
+++ b/src/Core/Dispatcher.php
@@ -34,13 +34,12 @@ public function __construct(ScenarioRepository $scenarioRepository, ScenarioRunn
      * @param \Keios\Apparatus\Contracts\Dispatchable $event
      *
      * @return mixed
+     * @throws \Keios\Apparatus\Exceptions\NoHandlerScenarioFoundException
      */
     public function dispatch(Dispatchable $event)
     {
         $scenario = $this->scenarioRepository->findHandlerScenarioFor($event);
 
-        $reaction = $this->scenarioRunner->run($scenario, $event);
-
-        return $reaction;
+        return $this->scenarioRunner->run($scenario, $event);
     }
 } 
\ No newline at end of file
diff --git a/src/Core/Event.php b/src/Core/Event.php
index 0bc1f11..510debd 100644
--- a/src/Core/Event.php
+++ b/src/Core/Event.php
@@ -94,6 +94,7 @@ public function expect(array $expectedReactions)
 
     /**
      * @return mixed
+     * @throws \Keios\Apparatus\Exceptions\NoHandlerScenarioFoundException
      */
     public function getReaction()
     {
diff --git a/src/Core/Scenario.php b/src/Core/Scenario.php
index 1ff9714..3827c9c 100644
--- a/src/Core/Scenario.php
+++ b/src/Core/Scenario.php
@@ -117,6 +117,9 @@ public function has($property)
 
     /**
      * @return mixed
+     * @throws \Keios\Apparatus\Exceptions\NoStepForEventFoundException
+     * @throws \Keios\Apparatus\Exceptions\NotInitializedException
+     * @throws \Keios\Apparatus\Exceptions\NoStepsDefinedException
      */
     public function run()
     {
@@ -158,6 +161,9 @@ public function dispatch($eventName, $data, array $expectedReactions)
 
     /**
      * @param \Keios\Apparatus\Core\Step $step
+     *
+     * @throws \Keios\Apparatus\Exceptions\EventAlreadyRegisteredException
+     * @throws \Keios\Apparatus\Exceptions\StepAlreadyRegisteredException
      */
     public function add(Step $step)
     {
@@ -168,6 +174,9 @@ public function add(Step $step)
     /**
      * @param                            $stepName
      * @param \Keios\Apparatus\Core\Step $step
+     *
+     * @throws \Keios\Apparatus\Exceptions\NoStepWithNameFoundException
+     * @throws \Keios\Apparatus\Exceptions\EventAlreadyRegisteredException
      */
     public function replace($stepName, Step $step)
     {
@@ -177,6 +186,8 @@ public function replace($stepName, Step $step)
     /**
      * @param                            $stepName
      * @param \Keios\Apparatus\Core\Step $step
+     *
+     * @throws \Keios\Apparatus\Exceptions\EventAlreadyRegisteredException
      */
     public function insertBefore($stepName, Step $step)
     {
@@ -186,6 +197,8 @@ public function insertBefore($stepName, Step $step)
     /**
      * @param                            $stepName
      * @param \Keios\Apparatus\Core\Step $step
+     *
+     * @throws \Keios\Apparatus\Exceptions\EventAlreadyRegisteredException
      */
     public function insertAfter($stepName, Step $step)
     {
diff --git a/src/Core/ScenarioFactory.php b/src/Core/ScenarioFactory.php
index 7ef16b2..52f593a 100644
--- a/src/Core/ScenarioFactory.php
+++ b/src/Core/ScenarioFactory.php
@@ -32,6 +32,7 @@ public function __construct(LoaderInterface $scenarioLoader)
      * @param \Keios\Apparatus\Contracts\Dispatchable $event
      *
      * @return mixed
+     * @throws \Keios\Apparatus\Exceptions\InvalidScenarioException
      * @throws \Keios\Apparatus\Exceptions\NoHandlerScenarioFoundException
      */
     public function findHandlerScenarioFor(Dispatchable $event)
@@ -93,11 +94,9 @@ protected function make($eventName)
     protected function resolveClosure($closure)
     {
         $scenario = $closure();
-
-        if ($interfaces = class_implements($scenario)) {
-            if (in_array('Keios\Apparatus\Contracts\Runnable', $interfaces)) {
+        $interfaces = class_implements($scenario);
+        if ($interfaces && in_array('Keios\Apparatus\Contracts\Runnable', $interfaces, true)) {
                 return is_object($scenario) ? $scenario : new $scenario();
-            }
         }
 
         throw new InvalidScenarioException(
diff --git a/src/Core/ScenarioRepository.php b/src/Core/ScenarioRepository.php
index 570bb93..fecb539 100644
--- a/src/Core/ScenarioRepository.php
+++ b/src/Core/ScenarioRepository.php
@@ -31,6 +31,8 @@ public function __construct(ScenarioFactory $scenarioFactory)
      * @param \Keios\Apparatus\Contracts\Dispatchable $event
      *
      * @return mixed
+     * @throws \Keios\Apparatus\Exceptions\InvalidScenarioException
+     * @throws \Keios\Apparatus\Exceptions\NoHandlerScenarioFoundException
      */
     public function findHandlerScenarioFor(Dispatchable $event)
     {
diff --git a/src/Core/ScenarioStepsList.php b/src/Core/ScenarioStepsList.php
index 407e78c..d1963ac 100644
--- a/src/Core/ScenarioStepsList.php
+++ b/src/Core/ScenarioStepsList.php
@@ -33,7 +33,7 @@ class ScenarioStepsList
     /**
      * @var null|Step
      */
-    protected $currentStep = null;
+    protected $currentStep;
 
     /**
      * @var \Keios\Apparatus\Contracts\Runnable
@@ -52,6 +52,7 @@ public function __construct(Runnable $scenario)
      * @param $eventName
      *
      * @throws \Keios\Apparatus\Exceptions\NoStepsDefinedException
+     * @throws \Keios\Apparatus\Exceptions\NoStepForEventFoundException
      */
     public function initialize($eventName)
     {
@@ -117,6 +118,7 @@ public function getPreviousStep()
 
     /**
      * @return bool
+     * @throws \Keios\Apparatus\Exceptions\NotInitializedException
      */
     public function hasNextStep()
     {
@@ -125,6 +127,7 @@ public function hasNextStep()
 
     /**
      * @return bool
+     * @throws \Keios\Apparatus\Exceptions\NotInitializedException
      */
     public function hasPreviousStep()
     {
@@ -133,6 +136,7 @@ public function hasPreviousStep()
 
     /**
      *
+     * @throws \Keios\Apparatus\Exceptions\NotInitializedException
      */
     public function moveToNextStep()
     {
@@ -142,6 +146,7 @@ public function moveToNextStep()
 
     /**
      *
+     * @throws \Keios\Apparatus\Exceptions\NotInitializedException
      */
     public function moveToPreviousStep()
     {
@@ -202,6 +207,9 @@ public function getStepForEvent($eventName)
     /**
      * @param                            $stepName
      * @param \Keios\Apparatus\Core\Step $step
+     *
+     * @throws \Keios\Apparatus\Exceptions\EventAlreadyRegisteredException
+     * @throws \Keios\Apparatus\Exceptions\NoStepWithNameFoundException
      */
     public function insertAfter($stepName, Step $step)
     {
@@ -211,6 +219,9 @@ public function insertAfter($stepName, Step $step)
     /**
      * @param                            $stepName
      * @param \Keios\Apparatus\Core\Step $step
+     *
+     * @throws \Keios\Apparatus\Exceptions\EventAlreadyRegisteredException
+     * @throws \Keios\Apparatus\Exceptions\NoStepWithNameFoundException
      */
     public function insertBefore($stepName, Step $step)
     {
@@ -222,6 +233,7 @@ public function insertBefore($stepName, Step $step)
      * @param \Keios\Apparatus\Core\Step $replacingStep
      *
      * @throws \Keios\Apparatus\Exceptions\NoStepWithNameFoundException
+     * @throws \Keios\Apparatus\Exceptions\EventAlreadyRegisteredException
      */
     public function replace($stepNameToReplace, Step $replacingStep)
     {

From c36a3ee1e8cd60f17bbe2b8bafbe72018b3d1a86 Mon Sep 17 00:00:00 2001
From: Kuba <jakub@keios.eu>
Date: Fri, 12 Aug 2016 13:25:27 +0200
Subject: [PATCH 2/2] further phpdocs and code inspect corrections

---
 src/Contracts/Dispatchable.php     |  9 ++++++++-
 src/Contracts/LoaderInterface.php  |  7 +++++++
 src/Contracts/Runnable.php         | 24 ++++++++++++++++++++++++
 src/Core/Dispatcher.php            |  1 +
 src/Core/Event.php                 |  4 ++--
 src/Core/Scenario.php              | 12 +++++++++---
 src/Core/ScenarioConfiguration.php |  8 ++++----
 src/Core/ScenarioFactory.php       |  4 ++--
 src/Core/ScenarioRunner.php        |  2 +-
 src/Core/ScenarioStepsList.php     | 22 ++++++++++------------
 src/Core/SideAction.php            |  6 ++++++
 src/Core/Step.php                  | 15 +++++++--------
 12 files changed, 81 insertions(+), 33 deletions(-)

diff --git a/src/Contracts/Dispatchable.php b/src/Contracts/Dispatchable.php
index c759488..45c4406 100644
--- a/src/Contracts/Dispatchable.php
+++ b/src/Contracts/Dispatchable.php
@@ -1,12 +1,17 @@
 <?php namespace Keios\Apparatus\Contracts;
 
 
+/**
+ * Interface Dispatchable
+ * @package Keios\Apparatus\Contracts
+ */
 interface Dispatchable
 {
 
     /**
      * @fluent
-     * @param $eventName
+     *
+     * @param string $eventName
      *
      * @return Dispatchable
      */
@@ -14,6 +19,7 @@ public function name($eventName);
 
     /**
      * @fluent
+     *
      * @param $data
      *
      * @return Dispatchable
@@ -22,6 +28,7 @@ public function with($data);
 
     /**
      * @fluent
+     *
      * @param array $expectedReactions
      *
      * @return Dispatchable
diff --git a/src/Contracts/LoaderInterface.php b/src/Contracts/LoaderInterface.php
index 39da681..344efc1 100644
--- a/src/Contracts/LoaderInterface.php
+++ b/src/Contracts/LoaderInterface.php
@@ -1,7 +1,14 @@
 <?php namespace Keios\Apparatus\Contracts;
 
 
+/**
+ * Interface LoaderInterface
+ * @package Keios\Apparatus\Contracts
+ */
 interface LoaderInterface
 {
+    /**
+     * @return mixed
+     */
     public function loadScenarios();
 }
\ No newline at end of file
diff --git a/src/Contracts/Runnable.php b/src/Contracts/Runnable.php
index 1bcc0ab..124033d 100644
--- a/src/Contracts/Runnable.php
+++ b/src/Contracts/Runnable.php
@@ -2,13 +2,37 @@
 
 use Keios\Apparatus\Core\Dispatcher;
 
+/**
+ * Interface Runnable
+ * @package Keios\Apparatus\Contracts
+ */
 interface Runnable
 {
+    /**
+     * @param Dispatchable $event
+     *
+     * @return mixed
+     */
     public function inject(Dispatchable $event);
 
+    /**
+     * @param Dispatcher $dispatcher
+     *
+     * @return mixed
+     */
     public function setDispatcher(Dispatcher $dispatcher);
 
+    /**
+     * @return mixed
+     */
     public function run();
 
+    /**
+     * @param string $eventName
+     * @param        $data
+     * @param array  $expectedReactions
+     *
+     * @return mixed
+     */
     public function dispatch($eventName, $data, array $expectedReactions);
 } 
\ No newline at end of file
diff --git a/src/Core/Dispatcher.php b/src/Core/Dispatcher.php
index acb72eb..c285270 100644
--- a/src/Core/Dispatcher.php
+++ b/src/Core/Dispatcher.php
@@ -34,6 +34,7 @@ public function __construct(ScenarioRepository $scenarioRepository, ScenarioRunn
      * @param \Keios\Apparatus\Contracts\Dispatchable $event
      *
      * @return mixed
+     * @throws \Keios\Apparatus\Exceptions\InvalidScenarioException
      * @throws \Keios\Apparatus\Exceptions\NoHandlerScenarioFoundException
      */
     public function dispatch(Dispatchable $event)
diff --git a/src/Core/Event.php b/src/Core/Event.php
index 510debd..287708a 100644
--- a/src/Core/Event.php
+++ b/src/Core/Event.php
@@ -54,7 +54,7 @@ public function name($eventName)
     /**
      * @fluent
      *
-     * @param $eventName
+     * @param string $eventName
      *
      * @return \Keios\Apparatus\Contracts\Dispatchable $this
      */
@@ -103,7 +103,7 @@ public function getReaction()
     }
 
     /**
-     * @return mixed
+     * @return string|null
      */
     public function getEventName()
     {
diff --git a/src/Core/Scenario.php b/src/Core/Scenario.php
index 3827c9c..f6fcef8 100644
--- a/src/Core/Scenario.php
+++ b/src/Core/Scenario.php
@@ -65,6 +65,8 @@ public function __construct()
 
     /**
      * @param \Keios\Apparatus\Core\Dispatcher $dispatcher
+     *
+     * @return mixed|void
      */
     public function setDispatcher(Dispatcher $dispatcher)
     {
@@ -73,6 +75,8 @@ public function setDispatcher(Dispatcher $dispatcher)
 
     /**
      * @param \Keios\Apparatus\Contracts\Dispatchable $event
+     *
+     * @return mixed|void
      */
     public function inject(Dispatchable $event)
     {
@@ -146,9 +150,9 @@ public function run()
     }
 
     /**
-     * @param       $eventName
-     * @param       $data
-     * @param array $expectedReactions
+     * @param string $eventName
+     * @param        $data
+     * @param array  $expectedReactions
      *
      * @return mixed
      */
@@ -188,6 +192,7 @@ public function replace($stepName, Step $step)
      * @param \Keios\Apparatus\Core\Step $step
      *
      * @throws \Keios\Apparatus\Exceptions\EventAlreadyRegisteredException
+     * @throws \Keios\Apparatus\Exceptions\NoStepWithNameFoundException
      */
     public function insertBefore($stepName, Step $step)
     {
@@ -199,6 +204,7 @@ public function insertBefore($stepName, Step $step)
      * @param \Keios\Apparatus\Core\Step $step
      *
      * @throws \Keios\Apparatus\Exceptions\EventAlreadyRegisteredException
+     * @throws \Keios\Apparatus\Exceptions\NoStepWithNameFoundException
      */
     public function insertAfter($stepName, Step $step)
     {
diff --git a/src/Core/ScenarioConfiguration.php b/src/Core/ScenarioConfiguration.php
index 35f02a3..3d873b3 100644
--- a/src/Core/ScenarioConfiguration.php
+++ b/src/Core/ScenarioConfiguration.php
@@ -18,8 +18,8 @@ class ScenarioConfiguration implements LoaderInterface
     protected $registeredScenarios = [];
 
     /**
-     * @param $eventName
-     * @param $scenarioClassName
+     * @param string $eventName
+     * @param string $scenarioClassName
      *
      * @throws \Keios\Apparatus\Exceptions\InvalidScenarioException
      * @throws \Keios\Apparatus\Exceptions\ScenarioNotFoundException
@@ -38,7 +38,7 @@ public function bind($eventName, $scenarioClassName)
     }
 
     /**
-     * @param $scenarioClassName
+     * @param string $scenarioClassName
      *
      * @throws \Keios\Apparatus\Exceptions\ScenarioNotFoundException
      */
@@ -52,7 +52,7 @@ protected function assertScenarioExists($scenarioClassName)
     }
 
     /**
-     * @param $scenarioClassName
+     * @param string $scenarioClassName
      *
      * @throws \Keios\Apparatus\Exceptions\InvalidScenarioException
      */
diff --git a/src/Core/ScenarioFactory.php b/src/Core/ScenarioFactory.php
index 52f593a..b30b4ce 100644
--- a/src/Core/ScenarioFactory.php
+++ b/src/Core/ScenarioFactory.php
@@ -45,7 +45,7 @@ public function findHandlerScenarioFor(Dispatchable $event)
     }
 
     /**
-     * @param $eventName
+     * @param string $eventName
      *
      * @return bool
      */
@@ -105,7 +105,7 @@ protected function resolveClosure($closure)
     }
 
     /**
-     * @param $eventName
+     * @param string $eventName
      *
      * @throws \Keios\Apparatus\Exceptions\NoHandlerScenarioFoundException
      */
diff --git a/src/Core/ScenarioRunner.php b/src/Core/ScenarioRunner.php
index 6b9514b..e65270d 100644
--- a/src/Core/ScenarioRunner.php
+++ b/src/Core/ScenarioRunner.php
@@ -11,7 +11,7 @@
 class ScenarioRunner
 {
     /**
-     * @var
+     * @var Dispatcher
      */
     protected $dispatcher;
 
diff --git a/src/Core/ScenarioStepsList.php b/src/Core/ScenarioStepsList.php
index d1963ac..66e270b 100644
--- a/src/Core/ScenarioStepsList.php
+++ b/src/Core/ScenarioStepsList.php
@@ -135,7 +135,6 @@ public function hasPreviousStep()
     }
 
     /**
-     *
      * @throws \Keios\Apparatus\Exceptions\NotInitializedException
      */
     public function moveToNextStep()
@@ -145,7 +144,6 @@ public function moveToNextStep()
     }
 
     /**
-     *
      * @throws \Keios\Apparatus\Exceptions\NotInitializedException
      */
     public function moveToPreviousStep()
@@ -155,7 +153,7 @@ public function moveToPreviousStep()
     }
 
     /**
-     * @param $stepName
+     * @param string $stepName
      *
      * @throws \Keios\Apparatus\Exceptions\NoStepWithNameFoundException
      */
@@ -182,7 +180,7 @@ public function add(Step $step)
     }
 
     /**
-     * @param $stepName
+     * @param string $stepName
      *
      * @return bool
      */
@@ -192,7 +190,7 @@ public function hasStepNamed($stepName)
     }
 
     /**
-     * @param $eventName
+     * @param string $eventName
      *
      * @return mixed
      * @throws \Keios\Apparatus\Exceptions\NoStepForEventFoundException
@@ -205,7 +203,7 @@ public function getStepForEvent($eventName)
     }
 
     /**
-     * @param                            $stepName
+     * @param string                     $stepName
      * @param \Keios\Apparatus\Core\Step $step
      *
      * @throws \Keios\Apparatus\Exceptions\EventAlreadyRegisteredException
@@ -217,7 +215,7 @@ public function insertAfter($stepName, Step $step)
     }
 
     /**
-     * @param                            $stepName
+     * @param string                     $stepName
      * @param \Keios\Apparatus\Core\Step $step
      *
      * @throws \Keios\Apparatus\Exceptions\EventAlreadyRegisteredException
@@ -229,7 +227,7 @@ public function insertBefore($stepName, Step $step)
     }
 
     /**
-     * @param                            $stepNameToReplace
+     * @param string                     $stepNameToReplace
      * @param \Keios\Apparatus\Core\Step $replacingStep
      *
      * @throws \Keios\Apparatus\Exceptions\NoStepWithNameFoundException
@@ -259,7 +257,7 @@ public function replace($stepNameToReplace, Step $replacingStep)
     }
 
     /**
-     * @param                            $stepName
+     * @param string                     $stepName
      * @param \Keios\Apparatus\Core\Step $step
      * @param bool                       $after
      *
@@ -323,7 +321,7 @@ protected function assertUniqueEventBinding(array $eventNames)
     }
 
     /**
-     * @param $stepName
+     * @param string $stepName
      *
      * @throws \Keios\Apparatus\Exceptions\StepAlreadyRegisteredException
      */
@@ -337,7 +335,7 @@ protected function assertUniqueStepName($stepName)
     }
 
     /**
-     * @param $eventName
+     * @param string $eventName
      *
      * @throws \Keios\Apparatus\Exceptions\NoStepForEventFoundException
      */
@@ -371,7 +369,7 @@ protected function assertIsInitialized()
     }
 
     /**
-     * @param $stepName
+     * @param string $stepName
      *
      * @throws \Keios\Apparatus\Exceptions\NoStepWithNameFoundException
      */
diff --git a/src/Core/SideAction.php b/src/Core/SideAction.php
index 10855d6..106420e 100644
--- a/src/Core/SideAction.php
+++ b/src/Core/SideAction.php
@@ -9,6 +9,12 @@
  */
 abstract class SideAction extends Action
 {
+    /**
+     * @param Runnable $scenario
+     * @param          $result
+     *
+     * @return mixed|void
+     */
     public function __invoke(Runnable $scenario, $result)
     {
         $this->scenario = $scenario;
diff --git a/src/Core/Step.php b/src/Core/Step.php
index 4313cdb..14a1045 100644
--- a/src/Core/Step.php
+++ b/src/Core/Step.php
@@ -15,7 +15,7 @@ class Step
     protected static $sideActionsCache = [];
 
     /**
-     * @var
+     * @var string
      */
     protected $name;
 
@@ -25,7 +25,7 @@ class Step
     protected $action;
 
     /**
-     * @var
+     * @var Runnable
      */
     protected $scenario;
 
@@ -40,7 +40,7 @@ class Step
     protected $sideActions = [];
 
     /**
-     * @param          $name
+     * @param string   $name
      * @param callable $action
      * @param array    $triggeringEvents
      */
@@ -80,7 +80,7 @@ public function __invoke($lastStepResult)
     }
 
     /**
-     * @return mixed
+     * @return string|null
      */
     public function getName()
     {
@@ -97,7 +97,9 @@ public function getTriggeringEvents()
 
     /**
      * @fluent
+     *
      * @param callable $sideAction
+     *
      * @return Step
      */
     public function with(callable $sideAction)
@@ -107,9 +109,6 @@ public function with(callable $sideAction)
         return $this;
     }
 
-    /**
-     *
-     */
     protected function importSideActions()
     {
         if (isset(static::$sideActionsCache[$this->name]) && is_array(static::$sideActionsCache[$this->name])) {
@@ -143,7 +142,7 @@ protected function executeSideActions($result)
     }
 
     /**
-     * @param          $stepName
+     * @param string   $stepName
      * @param callable $sideAction
      */
     public static function addSideAction($stepName, callable $sideAction)