Improve API documentation

Author: clue

README.md

@@ -26,6 +26,7 @@ whatsoever!*
 
 * [Usage](#usage)
     * [parallel()](#parallel)
+    * [series()](#series)
     * [waterfall()](#waterfall)
 * [Todo](#todo)
 * [Install](#install)
@@ -61,6 +62,9 @@ Async\parallel(…);
 
 ### parallel()
 
+The `parallel(array<callable> $tasks, ?callable $callback = null, ?callable $errback = null): void` function can be used
+like this:
+
 ```php
 <?php
 
@@ -89,14 +93,56 @@ React\Async\parallel(
             var_dump($result);
         }
     },
-    function (\Exception $e) {
+    function (Exception $e) {
+        throw $e;
+    }
+);
+```
+
+### series()
+
+The `series(array<callable> $tasks, ?callable $callback = null, ?callable $errback = null): void` function can be used
+like this:
+
+```php
+<?php
+
+use React\EventLoop\Loop;
+
+React\Async\series(
+    array(
+        function ($callback, $errback) {
+            Loop::addTimer(1, function () use ($callback) {
+                $callback('Slept for a whole second');
+            });
+        },
+        function ($callback, $errback) {
+            Loop::addTimer(1, function () use ($callback) {
+                $callback('Slept for another whole second');
+            });
+        },
+        function ($callback, $errback) {
+            Loop::addTimer(1, function () use ($callback) {
+                $callback('Slept for yet another whole second');
+            });
+        },
+    ),
+    function (array $results) {
+        foreach ($results as $result) {
+            var_dump($result);
+        }
+    },
+    function (Exception $e) {
         throw $e;
     }
 );
 ```
 
 ### waterfall()
 
+The `waterfall(array<callable> $tasks, ?callable $callback = null, ?callable $errback = null): void` function can be used
+like this:
+
 ```php
 <?php
 

src/functions.php

@@ -2,16 +2,17 @@
 
 namespace React\Async;
 
-function parallel($tasks, $callback = null, $errback = null)
+/**
+ * @param array<callable> $tasks
+ * @param ?callable       $callback
+ * @param ?callable       $errback
+ * @return void
+ */
+function parallel(array $tasks, $callback = null, $errback = null)
 {
     $results = array();
     $errors = array();
 
-    $taskErrback = function ($error) use (&$errors, &$checkDone) {
-        $errors[] = $error;
-        $checkDone();
-    };
-
     $done = function () use (&$results, &$errors, $callback, $errback) {
         if (!$callback) {
             return;
@@ -38,6 +39,11 @@ function parallel($tasks, $callback = null, $errback = null)
         }
     };
 
+    $taskErrback = function ($error) use (&$errors, $checkDone) {
+        $errors[] = $error;
+        $checkDone();
+    };
+
     foreach ($tasks as $i => $task) {
         $taskCallback = function ($result) use (&$results, $i, $checkDone) {
             $results[$i] = $result;
@@ -48,10 +54,17 @@ function parallel($tasks, $callback = null, $errback = null)
     }
 }
 
-function series($tasks, $callback = null, $errback = null)
+/**
+ * @param array<callable> $tasks
+ * @param ?callable       $callback
+ * @param ?callable       $errback
+ * @return void
+ */
+function series(array $tasks, $callback = null, $errback = null)
 {
     $results = array();
 
+    /** @var callable():void $next */
     $taskCallback = function ($result) use (&$results, &$next) {
         $results[] = $result;
         $next();
@@ -76,7 +89,13 @@ function series($tasks, $callback = null, $errback = null)
     $next();
 }
 
-function waterfall($tasks, $callback = null, $errback = null)
+/**
+ * @param array<callable> $tasks
+ * @param ?callable       $callback
+ * @param ?callable       $errback
+ * @return void
+ */
+function waterfall(array $tasks, $callback = null, $errback = null)
 {
     $taskCallback = function () use (&$next) {
         call_user_func_array($next, func_get_args());