From 42c337e793581cf0a73e26d68eb3de999a88aafb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christian=20L=C3=BCck?= <christian@clue.engineering>
Date: Sun, 17 Oct 2021 11:10:45 +0200
Subject: [PATCH] Improve documentation to use fully-qualified function names

---
 README.md                 | 30 +++++++++++++++++++-----------
 examples/01-await.php     |  4 +---
 examples/02-await-any.php |  4 +---
 examples/03-await-all.php |  4 +---
 src/functions.php         | 10 +++++-----
 5 files changed, 27 insertions(+), 25 deletions(-)

diff --git a/README.md b/README.md
index bbd1d16..a7545fa 100644
--- a/README.md
+++ b/README.md
@@ -65,7 +65,7 @@ function blockingExample()
     $request2 = $browser->get('http://www.google.co.uk/');
     
     // keep the loop running (i.e. block) until the first response arrives
-    $fasterResponse = Block\awaitAny(array($request1, $request2), $loop);
+    $fasterResponse = Clue\React\Block\awaitAny(array($request1, $request2), $loop);
     
     return $fasterResponse->getBody();
 }
@@ -76,18 +76,26 @@ function blockingExample()
 This lightweight library consists only of a few simple functions.
 All functions reside under the `Clue\React\Block` namespace.
 
-The below examples assume you use an import statement similar to this:
+The below examples refer to all functions with their fully-qualified names like this:
 
 ```php
-use Clue\React\Block;
+Clue\React\Block\await(…);
+```
 
-Block\await(…);
+As of PHP 5.6+ you can also import each required function into your code like this:
+
+```php
+use function Clue\React\Block\await;
+
+await(…);
 ```
 
-Alternatively, you can also refer to them with their fully-qualified name:
+Alternatively, you can also use an import statement similar to this:
 
 ```php
-\Clue\React\Block\await(…);
+use Clue\React\Block;
+
+Block\await(…);
 ```
 
 ### EventLoop
@@ -106,7 +114,7 @@ The `sleep($seconds, LoopInterface $loop): void` function can be used to
 wait/sleep for `$time` seconds.
 
 ```php
-Block\sleep(1.5, $loop);
+Clue\React\Block\sleep(1.5, $loop);
 ```
 
 This function will only return after the given `$time` has elapsed. In the
@@ -125,7 +133,7 @@ The `await(PromiseInterface $promise, LoopInterface $loop, ?float $timeout = nul
 block waiting for the given `$promise` to be fulfilled.
 
 ```php
-$result = Block\await($promise, $loop, $timeout);
+$result = Clue\React\Block\await($promise, $loop, $timeout);
 ```
 
 This function will only return after the given `$promise` has settled, i.e.
@@ -141,7 +149,7 @@ will throw an `UnexpectedValueException` instead.
 
 ```php
 try {
-    $result = Block\await($promise, $loop);
+    $result = Clue\React\Block\await($promise, $loop);
     // promise successfully fulfilled with $result
     echo 'Result: ' . $result;
 } catch (Exception $exception) {
@@ -171,7 +179,7 @@ $promises = array(
     $promise2
 );
 
-$firstResult = Block\awaitAny($promises, $loop, $timeout);
+$firstResult = Clue\React\Block\awaitAny($promises, $loop, $timeout);
 
 echo 'First result: ' . $firstResult;
 ```
@@ -208,7 +216,7 @@ $promises = array(
     $promise2
 );
 
-$allResults = Block\awaitAll($promises, $loop, $timeout);
+$allResults = Clue\React\Block\awaitAll($promises, $loop, $timeout);
 
 echo 'First promise resolved with: ' . $allResults[0];
 ```
diff --git a/examples/01-await.php b/examples/01-await.php
index 6cd035e..8e61f2b 100644
--- a/examples/01-await.php
+++ b/examples/01-await.php
@@ -1,7 +1,5 @@
 <?php
 
-use Clue\React\Block;
-
 require __DIR__ . '/../vendor/autoload.php';
 
 /**
@@ -22,7 +20,7 @@ function requestHttp($url)
 
     try {
         // keep the loop running (i.e. block) until the response arrives
-        $result = Block\await($promise, $loop);
+        $result = Clue\React\Block\await($promise, $loop);
 
         // promise successfully fulfilled with $result
         return $result;
diff --git a/examples/02-await-any.php b/examples/02-await-any.php
index 2b5d83a..e7578a3 100644
--- a/examples/02-await-any.php
+++ b/examples/02-await-any.php
@@ -1,7 +1,5 @@
 <?php
 
-use Clue\React\Block;
-
 require __DIR__ . '/../vendor/autoload.php';
 
 /**
@@ -26,7 +24,7 @@ function requestHttpFastestOfMultiple($url1, $url2)
 
     try {
         // keep the loop running (i.e. block) until the first response arrives
-        $fasterResponse = Block\awaitAny($promises, $loop);
+        $fasterResponse = Clue\React\Block\awaitAny($promises, $loop);
 
         // promise successfully fulfilled with $fasterResponse
         return $fasterResponse;
diff --git a/examples/03-await-all.php b/examples/03-await-all.php
index b2c470f..62ed03c 100644
--- a/examples/03-await-all.php
+++ b/examples/03-await-all.php
@@ -1,7 +1,5 @@
 <?php
 
-use Clue\React\Block;
-
 require __DIR__ . '/../vendor/autoload.php';
 
 /**
@@ -26,7 +24,7 @@ function requestHttpMultiple($url1, $url2)
 
     try {
         // keep the loop running (i.e. block) until all responses arrive
-        $allResults = Block\awaitAll($promises, $loop);
+        $allResults = Clue\React\Block\awaitAll($promises, $loop);
 
         // promise successfully fulfilled with $allResults
         return $allResults;
diff --git a/src/functions.php b/src/functions.php
index 0fda798..545e327 100644
--- a/src/functions.php
+++ b/src/functions.php
@@ -15,7 +15,7 @@
  * Wait/sleep for `$time` seconds.
  *
  * ```php
- * Block\sleep(1.5, $loop);
+ * Clue\React\Block\sleep(1.5, $loop);
  * ```
  *
  * This function will only return after the given `$time` has elapsed. In the
@@ -41,7 +41,7 @@ function sleep($time, LoopInterface $loop)
  * Block waiting for the given `$promise` to be fulfilled.
  *
  * ```php
- * $result = Block\await($promise, $loop, $timeout);
+ * $result = Clue\React\Block\await($promise, $loop, $timeout);
  * ```
  *
  * This function will only return after the given `$promise` has settled, i.e.
@@ -57,7 +57,7 @@ function sleep($time, LoopInterface $loop)
  *
  * ```php
  * try {
- *     $result = Block\await($promise, $loop);
+ *     $result = Clue\React\Block\await($promise, $loop);
  *     // promise successfully fulfilled with $result
  *     echo 'Result: ' . $result;
  * } catch (Exception $exception) {
@@ -140,7 +140,7 @@ function ($error) use (&$exception, &$rejected, &$wait, $loop) {
  *     $promise2
  * );
  *
- * $firstResult = Block\awaitAny($promises, $loop, $timeout);
+ * $firstResult = Clue\React\Block\awaitAny($promises, $loop, $timeout);
  *
  * echo 'First result: ' . $firstResult;
  * ```
@@ -220,7 +220,7 @@ function awaitAny(array $promises, LoopInterface $loop, $timeout = null)
  *     $promise2
  * );
  *
- * $allResults = Block\awaitAll($promises, $loop, $timeout);
+ * $allResults = Clue\React\Block\awaitAll($promises, $loop, $timeout);
  *
  * echo 'First promise resolved with: ' . $allResults[0];
  * ```