phpDoc + README update

Author: coff

README.md

@@ -1,15 +1,16 @@
 
+*Remark: It's a work-in-progress project! Wanna contribute? Let me know.*
+
 # State Machine Framework for PHP
 
-State Machines are not what you usually do with PHP but when you do... just use this.
+Maybe state machines are not what you usually do with PHP but when you do... just use this.
+
 
-  
-It's a work-in-progress project! Wanna contribute? Let me know.
+## Usage example
 
-Usage example:
+### State dictionary
 
 ```php
-<?php 
 
     class PetitionEnum extends StateEnum {
         const __default     = self::DRAFT,
@@ -21,14 +22,18 @@ Usage example:
               CANCELED      = 'canceled';
 
     }
+```
+### Machine class
 
+```php
     class Petition extends Machine {
 
         protected $votesYes, $votesNo;
 
         public function init() {
             $this->setInitState(PetitionEnum::DRAFT());
 
+            // defines machine's allowed behavior, when no Assertion is given uses DefaultCallbackAssertion
             $this
                 ->allowTransition(PetitionEnum::DRAFT(), PetitionEnum::SENT())
                 ->allowTransition(PetitionEnum::DRAFT(), PetitionEnum::CANCELED())
@@ -60,33 +65,19 @@ Usage example:
 
         public function assertSentToVoted() 
         {
-            if (null !== $this->votesYes && null !== $this->votesNo)
-            {
-                return true;
-            }
-            
-            return false;
+            // Method name used here is based upon DefaultCallbackAssertion. This can be changed though.
+            return (null !== $this->votesYes && null !== $this->votesNo) ? true : false;
         }
 
 
         public function assertVotedToAccepted()
         {
-            if ($this->votesYes > $this->votesNo) 
-            { 
-                return true;
-            }
-            
-            return false;
+            return $this->votesYes > $this->votesNo ? true : false;
         }
 
         public function assertVotedToRejected() 
         {
-            if ($this->votesYes <= $this->votesNo)
-            {
-                return true;
-            }    
-            
-            return false;
+            return $this->votesYes <= $this->votesNo ? true : false;
         }
 
         public function onTransition(Transition $transition) 
@@ -96,8 +87,12 @@ Usage example:
             echo 'State changed from ' . $transition->getFromState() . ' to ' . $transition->getToState() . PHP_EOL;
         }
     }
+```
+
+### Machine in-use    
 
-    
+```php
+
     $p = new Petition();
 
     $p->run();
@@ -115,9 +110,5 @@ Usage example:
     // State changed from sent to voted
     // State changed from voted to accepted
 
-    
-    
-    
-    
 ```    
 

src/Assertion/CallbackAssertion.php

@@ -33,6 +33,10 @@ public function setParams($params = []) {
         return $this;
     }
 
+    /**
+     * @return bool
+     * @throws AssertionException
+     */
     public function make(): bool
     {
         if ($this->callback) {

src/Assertion/CommonCallbackAssertion.php

@@ -35,7 +35,11 @@ public function setTransition(TransitionInterface $transition)
 
         return $this;
     }
-    
+
+    /**
+     * @return bool
+     * @throws AssertionException
+     */
     public function make(): bool
     {
         if ($this->object instanceof MachineInterface && $this->transition instanceof TransitionInterface) 

src/Assertion/DefaultCallbackAssertion.php

@@ -35,7 +35,11 @@ public function setTransition(TransitionInterface $transition)
 
         return $this;
     }
-    
+
+    /**
+     * @return bool
+     * @throws AssertionException
+     */
     public function make(): bool
     {
         if ($this->object instanceof MachineInterface && $this->transition instanceof TransitionInterface) 

src/Machine.php

@@ -141,9 +141,14 @@ public function assertTransition(Transition $transition) : bool
         return true;
     }
 
+    /**
+     * @return StateEnum
+     * @throws TransitionException
+     */
     public function run() {
 
         do {
+            $result = false;
 
             $allowedTrans = $this->getAllowedTransitions();
 
@@ -179,6 +184,7 @@ public function run() {
      * @param $newState
      * @return $this
      * @throws TransitionException
+     * @throws MachineException
      */
     protected function setMachineState(StateEnum $newState) {