updated docs for stacked stubs support

Author: DavertMik

CHANGELOG.md

@@ -2,9 +2,10 @@
 
 #### 2.0.0
 
-* **Updated to Go AOP Framework 1.0**
+* **Updated to Go AOP Framework 2.0**
 * PHP7 (with typehints) supported
 * Minimal PHP version is PHP 5.6
+* Stacked support for mocked methods. You can register a chain of methods as a stub, and to control their execution.
 
 #### 1.0.0
 

src/AspectMock/Test.php

@@ -84,6 +84,41 @@ class Test {
      * ?>
      * ```
      *
+     * #### Stacked Calls Support
+     *
+     * Since 2.0 you can register multiple functions inside stib which will be executed in chain.
+     * You can pass control to next function in a stack by returning `__AM_CONTINUE__` constant:
+     *
+     * ```php
+     * class User {
+     *     public function getGroup() { return 'guest'; }
+     * }
+     * $user = new User;
+     * ```
+     *
+     * So, it is for conflicted stubs, when a test double (e.g., getGroup) has been redefined.
+     *
+     * ```php
+     * $stub1 = function () {
+     *     return 'user';
+     * };
+     * $stub2 = function ($supersede = false) {
+     *  return $supersede ? 'root' : __AM_CONTINUE__;
+     * };
+     * test::double('User', ['getGroup' => $stub1]);
+     * test::double('User', ['getGroup' => $stub2]);
+     *
+     * ```
+     *
+     * The idea basically is to allow a chain of responsibility passing through every conflicted stubs until a result returns. Use stack structure so that the latest defined stub will gain highest priority.
+     * So, the result will look like this:
+     *
+     * ```php
+     * $user->getGroup(true) // => root (handled by $stub2)
+     * $user->getGroup() // => user (handled by $stub2 and then $stub1)
+     * ```
+     * The $user->getGroup() // => user first handled by $stub2 and it gives up control by returning __AM_CONTINUE__, $stub1 then take place and return "user". If $stub1 return __AM_CONTINUE__, it will return control to the real object, as every stub has returned __AM_CONTINUE__.
+     *
      * @api
      * @param string|object $classOrObject
      * @param array $params [ 'methodName' => 'returnValue' ]