mockery#459 - Documented new functionality

docs/reference/argument_validation.rst

@@ -78,6 +78,37 @@ not implemented in the current default matchers.
 
 There is no Hamcrest version of this functionality.
 
+.. code-block:: php
+
+    withArgs(closure)
+
+You can also perform argument validation by passing a closure to ``withArgs()``
+method. The closure will receive all arguments passed in the call to the expected
+method and if it evaluates (i.e. returns) to boolean ``true``, then the list of
+arguments is assumed to have matched the expectation. The closure can also
+handle optional parameters, so if an optional parameter is missing in the call
+to the expected method, it doesn't necessary means that the list of arguments
+doesn't match the expectation.
+
+.. code-block:: php
+
+    $closure = function ($odd, $even, $sum = null) {
+        $result = ($odd % 2 != 0) && ($even % 2 == 0);
+        if (!is_null($sum)) {
+            return $result && ($odd + $even == $sum);
+        }
+        return $result;
+    };
+    $this->mock->shouldReceive('foo')->withArgs($closure);
+
+    $this->mock->foo(1, 2); // It matches the expectation: the optional argument is not needed
+    $this->mock->foo(1, 2, 3); // It also matches the expectation: the optional argument pass the validation
+    $this->mock->foo(1, 2, 4); // It doesn't match the expectation: the optional doesn't pass the validation
+    $this->mock->foo(1, 2, 4, 5); // It neither match the expectation: there are too many arguments
+    $this->mock->foo(1); // It neither match the expectation: there are too few arguments
+
+
+
 .. code-block:: php
 
     with('/^foo/') OR with(matchesPattern('/^foo/'))

docs/reference/expectations.rst

@@ -65,6 +65,17 @@ the given method when it is called with these exact arguments. This allows for
 setting up differing expectations based on the arguments provided to expected
 calls.
 
+.. code-block:: php
+
+    withArgs(closure)
+
+Instead of providing a built-in matcher for each argument, you can provide a
+closure that matches all passed arguments at once. The given closure receives
+all the arguments passed in the call to the expected method. In this way, this
+expectation only applies to method calls where passed arguments make the closure
+evaluates to true. It can also handle optional arguments and takes care of the
+number of required arguments in the closure#
+
 .. code-block:: php
 
     withAnyArgs()