Converge docs (#205)

jasonmm · lstrojny · commit bf439a9b6350 · 2019-12-14T00:38:22.000+01:00
* Write docs for `converge`. Closes #188. * Fix a few typos in docs.
diff --git a/docs/functional-php.md b/docs/functional-php.md
@@ -23,6 +23,7 @@
   - [partial_left() & partial_right()](#partial_left--partial_right)
   - [partial_any()](#partial_any)
   - [partial_method()](#partial_method)
+  - [converge()](#converge)
 - [Currying](#currying)
   - [curry()](#curry)
   - [curry_n()](#curry_n)
@@ -411,6 +412,32 @@ $users = [new User(), new User()];
 $registeredUsers = select($users, partial_method('isRegistered'));
 ```
 
+## converge()
+
+``callable Functional\converge(callable $convergingFunction, callable[] branchingFunctions)``
+
+`converge` accepts a converging function and a list of branching functions and returns a new function.
+
+The returned function takes a variable number of arguments.
+
+The _converging function_ should take the same number of arguments as there are branching functions.
+
+Each _branching function_ should take the same number of arguments as the number of arguments passed in to the returned function.
+
+```php
+use function Functional\converge;
+
+function div($dividend, $divisor) {
+    return $dividend / $divisor;
+}
+
+$average = converge('div', ['array_sum', 'count']);
+$average([1, 2, 3, 4]); // -> 2.5
+```
+
+The returned function, in the above example it is named `$average`, passes each of its arguments to each branching function. `$average` then takes the return values of all the branching functions and passes each one as an argument to the converging function. The return value of the converging function is the return value of `$average`.
+
+
 # Currying
 
 Currying is similar to and often confused with partial application. But instead of binding parameters to some value and returning a new function, a curried function will take one parameter on each call and return a new function until all parameters are bound.
@@ -462,7 +489,7 @@ $curriedAdd = curry('add', true);
 $curriedAddWithOptional = curry('add', false);
 ```
 
-Starting with PHP7 and the implementation of the ["Uniform variable syntax"](https://wiki.php.net/rfc/uniform_variable_syntax), you can greatly simpliy the usage of curried functions.
+Starting with PHP7 and the implementation of the ["Uniform variable syntax"](https://wiki.php.net/rfc/uniform_variable_syntax), you can greatly simplify the usage of curried functions.
 
 ```php
 use function Functional\curry;
@@ -479,10 +506,10 @@ _Note, that you cannot use `curry` on a flipped function. `curry` uses reflectio
 
 ## curry_n()
 
-`curry` uses reflection to determine the number of arguments, which can be slow depdening on your requirements. Also, you might want to curry only the first parameters, or your function expects a variable number of parameters. In all cases, you can use `curry_n` instead.
+`curry` uses reflection to determine the number of arguments, which can be slow depending on your requirements. Also, you might want to curry only the first parameters, or your function expects a variable number of parameters. In all cases, you can use `curry_n` instead.
 
 ```php
-use function Functional\curry;
+use function Functional\curry_n;
 
 function add($a, $b, $c, $d) {
     return $a + $b + $c + $d;
