Merge pull request #58 from clue-labs/namespace-docs

Improve documentation to use fully-qualified function names

Author: SimonFrings

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];
 ```

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;

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;

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;

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) {
@@ -144,7 +144,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;
  * ```
@@ -224,7 +224,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];
  * ```