Updating README and docs

Author: Jean Claveau

README.md

@@ -18,8 +18,8 @@ php-deferred-callchain is installable via [Composer](http://getcomposer.org)
     composer require jclaveau/php-deferred-callchain
 
 ## Usage
+### Fluent call chain
 ```php
-// fluent call chain
 $nameRobert = (new DeferredCallChain)
     ->setName('Muda')
     ->setFirstName('Robert')
@@ -30,8 +30,10 @@ $robert = $nameRobert( $mySubjectIMissedBefore );
 
 echo $robert->getFullName(); // => "Robert Muda"
 echo (string) $nameRobert;   // => "(new JClaveau\Async\DeferredCallChain)->setName('Muda')->setFirstName('Robert')"
+```
 
-// working with arrays
+### Working with arrays
+```php
 $getSubColumnValue = (new DeferredCallChain)
     ['column_1']
     ['sub_column_3']

docs/README.md

@@ -4,27 +4,32 @@
 
 * [DeferredCallChain](#deferredcallchain)
     * [new_](#new_)
+    * [offsetGet](#offsetget)
     * [__call](#__call)
     * [jsonSerialize](#jsonserialize)
     * [__toString](#__tostring)
     * [__invoke](#__invoke)
+    * [offsetSet](#offsetset)
+    * [offsetExists](#offsetexists)
+    * [offsetUnset](#offsetunset)
 
 ## DeferredCallChain
 
-
+This class stores an arbitrary stack of calls (methods or array entries access)
+that will be callable on any future variable.
 
 
 
 * Full name: \JClaveau\Async\DeferredCallChain
-* This class implements: \JsonSerializable
+* This class implements: \JsonSerializable, \ArrayAccess
 
 
 ### new_
 
-
+Simple factory to avoid (new DeferredCallChain)
 
 ```php
-DeferredCallChain::new_(  )
+DeferredCallChain::new_(  ): $this
 ```
 
 
@@ -35,12 +40,34 @@ DeferredCallChain::new_(  )
 
 ---
 
-### __call
+### offsetGet
+
+ArrayAccess interface
+
+```php
+DeferredCallChain::offsetGet( string $key )
+```
+
+
+
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `$key` | **string** | The entry to acces |
+
+
+
+
+---
 
+### __call
 
+Stores any call in the the stack.
 
 ```php
-DeferredCallChain::__call(  $method, array $arguments )
+DeferredCallChain::__call( string $method, array $arguments ): $this
 ```
 
 
@@ -50,7 +77,7 @@ DeferredCallChain::__call(  $method, array $arguments )
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `$method` | **** |  |
+| `$method` | **string** |  |
 | `$arguments` | **array** |  |
 
 
@@ -79,16 +106,21 @@ DeferredCallChain::jsonSerialize(  )
 
 ### __toString
 
-
+Outputs the PHP code producing the current call chain while it's casted
+as a string.
 
 ```php
-DeferredCallChain::__toString(  )
+DeferredCallChain::__toString(  ): string
 ```
 
 
 
 
 
+**Return Value:**
+
+The PHP code corresponding to this call chain
+
 
 
 ---
@@ -98,7 +130,78 @@ DeferredCallChain::__toString(  )
 Invoking the instance produces the call of the stack
 
 ```php
-DeferredCallChain::__invoke(  $target )
+DeferredCallChain::__invoke(  $target ): \JClaveau\Async\The
+```
+
+
+
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `$target` | **** | The target to apply the callchain on |
+
+
+**Return Value:**
+
+value returned once the call chain is called uppon $target
+
+
+
+---
+
+### offsetSet
+
+Unused part of the ArrayAccess interface
+
+```php
+DeferredCallChain::offsetSet(  $offset,  $value )
+```
+
+
+
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `$offset` | **** |  |
+| `$value` | **** |  |
+
+
+
+
+---
+
+### offsetExists
+
+Unused part of the ArrayAccess interface
+
+```php
+DeferredCallChain::offsetExists(  $offset )
+```
+
+
+
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `$offset` | **** |  |
+
+
+
+
+---
+
+### offsetUnset
+
+Unused part of the ArrayAccess interface
+
+```php
+DeferredCallChain::offsetUnset(  $offset )
 ```
 
 
@@ -108,7 +211,7 @@ DeferredCallChain::__invoke(  $target )
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `$target` | **** |  |
+| `$offset` | **** |  |
 
 
 
@@ -118,4 +221,4 @@ DeferredCallChain::__invoke(  $target )
 
 
 --------
-> This document was automatically generated from source code comments on 2018-11-06 using [phpDocumentor](http://www.phpdoc.org/) and [cvuorinen/phpdoc-markdown-public](https://github.com/cvuorinen/phpdoc-markdown-public)
+> This document was automatically generated from source code comments on 2018-11-14 using [phpDocumentor](http://www.phpdoc.org/) and [cvuorinen/phpdoc-markdown-public](https://github.com/cvuorinen/phpdoc-markdown-public)

src/DeferredCallChain.php

@@ -6,15 +6,21 @@
  * @author  Jean Claveau
  */
 namespace JClaveau\Async;
+use       BadMethodCallException;
 
 /**
+ * This class stores an arbitrary stack of calls (methods or array entries access)
+ * that will be callable on any future variable.
  */
 class DeferredCallChain implements \JsonSerializable, \ArrayAccess
 {
-    /** @var */
+    /** @var array $stack The stack of deferred calls */
     protected $stack = [];
 
     /**
+     * Simple factory to avoid (new DeferredCallChain)
+     *
+     * @return $this
      */
     public static function new_()
     {
@@ -23,6 +29,8 @@ public static function new_()
 
     /**
      * ArrayAccess interface
+     *
+     * @param string $key The entry to acces
      */
     public function &offsetGet($key)
     {
@@ -34,6 +42,8 @@ public function &offsetGet($key)
     }
 
     /**
+     * Stores any call in the the stack.
+     *
      * @param  string $method
      * @param  array  $arguments
      *
@@ -60,6 +70,10 @@ public function jsonSerialize()
     }
 
     /**
+     * Outputs the PHP code producing the current call chain while it's casted
+     * as a string.
+     *
+     * @return string The PHP code corresponding to this call chain
      */
     public function __toString()
     {
@@ -84,6 +98,9 @@ public function __toString()
 
     /**
      * Invoking the instance produces the call of the stack
+     *
+     * @param  $target The target to apply the callchain on
+     * @return The value returned once the call chain is called uppon $target
      */
     public function __invoke($target)
     {
@@ -107,31 +124,41 @@ public function __invoke($target)
     }
 
     /**
-     * ArrayAccess interface
+     * Unused part of the ArrayAccess interface
+     *
+     * @param  $offset
+     * @param  $value
+     * @throws \BadMethodCallException
      */
     public function offsetSet($offset, $value)
     {
-        throw new \BadMethodCallException(
+        throw new BadMethodCallException(
             "not implemented"
         );
     }
 
     /**
-     * ArrayAccess interface
+     * Unused part of the ArrayAccess interface
+     *
+     * @param  $offset
+     * @throws \BadMethodCallException
      */
     public function offsetExists($offset)
     {
-        throw new \BadMethodCallException(
+        throw new BadMethodCallException(
             "not implemented"
         );
     }
 
     /**
-     * ArrayAccess interface
+     * Unused part of the ArrayAccess interface
+     *
+     * @param  $offset
+     * @throws \BadMethodCallException
      */
     public function offsetUnset($offset)
     {
-        throw new \BadMethodCallException(
+        throw new BadMethodCallException(
             "not implemented"
         );
     }