Merge pull request #126 from clue-labs/docs

Minor documentation improvements

Author: jsor

README.md

@@ -32,7 +32,7 @@ Here is an async HTTP server built with just the event loop.
 $loop = React\EventLoop\Factory::create();
 
 $server = stream_socket_server('tcp://127.0.0.1:8080');
-stream_set_blocking($server, 0);
+stream_set_blocking($server, false);
 
 $loop->addReadStream($server, function ($server) use ($loop) {
     $conn = stream_socket_accept($server);
@@ -97,7 +97,7 @@ $loop->run();
 ## Factory
 
 The `Factory` class exists as a convenient way to pick the best available
-[loop implementation)(#loop-implementation).
+[loop implementation](#loop-implementations).
 
 The `create(): LoopInterface` method can be used to create a new loop
 instance:
@@ -170,14 +170,14 @@ If you want to access any variables within your callback function, you
 can bind arbitrary data to a callback closure like this:
 
 ```php
-function hello(LoopInterface $loop, $name)
+function hello($name, LoopInterface $loop)
 {
     $loop->addTimer(1.0, function () use ($name) {
         echo "hello $name\n";
     });
 }
 
-hello('Tester');
+hello('Tester', $loop);
 ```
 
 The execution order of timers scheduled to execute at the same time is
@@ -218,7 +218,7 @@ If you want to limit the number of executions, you can bind
 arbitrary data to a callback closure like this:
 
 ```php
-function hello(LoopInterface $loop, $name)
+function hello($name, LoopInterface $loop)
 {
     $n = 3;
     $loop->addPeriodicTimer(1.0, function ($timer) use ($name, $loop, &$n) {
@@ -231,7 +231,7 @@ function hello(LoopInterface $loop, $name)
     });
 }
 
-hello('Tester');
+hello('Tester', $loop);
 ```
 
 The execution order of timers scheduled to execute at the same time is
@@ -245,11 +245,12 @@ cancel a pending timer.
 See also [`addPeriodicTimer()`](#addperiodictimer) and [example #2](examples).
 
 You can use the [`isTimerActive()`](#istimeractive) method to check if
-this timer is still "active". After a timer is successfully canceled,
+this timer is still "active". After a timer is successfully cancelled,
 it is no longer considered "active".
 
 Calling this method on a timer instance that has not been added to this
-loop instance or on a timer
+loop instance or on a timer that is not "active" (or has already been
+cancelled) has no effect.
 
 ### isTimerActive()
 
@@ -258,7 +259,7 @@ check if a given timer is active.
 
 A timer is considered "active" if it has been added to this loop instance
 via [`addTimer()`](#addtimer) or [`addPeriodicTimer()`](#addperiodictimer)
-and has not been canceled via [`cancelTimer()`](#canceltimer) and is not
+and has not been cancelled via [`cancelTimer()`](#canceltimer) and is not
 a non-periodic timer that has already been triggered after its interval.
 
 ### futureTick()
@@ -280,14 +281,14 @@ If you want to access any variables within your callback function, you
 can bind arbitrary data to a callback closure like this:
 
 ```php
-function hello(LoopInterface $loop, $name)
+function hello($name, LoopInterface $loop)
 {
     $loop->futureTick(function () use ($name) {
         echo "hello $name\n";
     });
 }
 
-hello('Tester');
+hello('Tester', $loop);
 ```
 
 Unlike timers, tick callbacks are guaranteed to be executed in the order
@@ -312,8 +313,10 @@ See also [example #3](examples).
 ### addSignal()
 
 The `addSignal(int $signal, callable $listener): void` method can be used to
-be notified about OS signals. This is useful to catch user interrupt signals or 
-shutdown signals from tools like `supervisor` or `systemd`.
+register a listener to be notified when a signal has been caught by this process.
+
+This is useful to catch user interrupt signals or shutdown signals from
+tools like `supervisor` or `systemd`.
 
 The listener callback function MUST be able to accept a single parameter,
 the signal added by this method or you MAY use a function which
@@ -325,32 +328,32 @@ no effect, so for performance reasons you're recommended to not return
 any excessive data structures.
 
 ```php
-$listener = function (int $signal) {
-    echo 'Caught user iterrupt signal', PHP_EOL;
-};
-$loop->addSignal(SIGINT, $listener);
+$loop->addSignal(SIGINT, function (int $signal) {
+    echo 'Caught user interrupt signal' . PHP_EOL;
+});
 ```
 
 See also [example #4](examples).
 
-**Note: A listener can only be added once to the same signal, any attempts to add it 
-more then once will be ignored.**
+Signaling is only available on Unix-like platform, Windows isn't
+supported due to operating system limitations.
+This method may throw a `BadMethodCallException` if signals aren't
+supported on this platform, for example when required extensions are
+missing.
 
-**Note: Signaling is only available on Unix-like platform, Windows isn't supported due 
-to limitations from underlying signal handlers.**
+**Note: A listener can only be added once to the same signal, any
+attempts to add it more then once will be ignored.**
 
 ### removeSignal()
 
-The `removeSignal(int $signal, callable $listener): void` removes a previously added 
-signal listener.
-
-Any attempts to remove listeners that aren't registerred will be ignored.
+The `removeSignal(int $signal, callable $listener): void` method can be used to
+remove a previously added signal listener.
 
 ```php
 $loop->removeSignal(SIGINT, $listener);
 ```
 
-See also [example #4](examples).
+Any attempts to remove listeners that aren't registered will be ignored.
 
 ### addReadStream()
 

src/ExtEventLoop.php

@@ -42,7 +42,7 @@ function ($signal) {
                     $this->signals->call($signal);
                     // Ensure there are two copies of the callable around until it has been executed.
                     // For more information see: https://bugs.php.net/bug.php?id=62452
-                    // Only an issue for PHP 5, this hack can be removed once PHP 5 suppose has been dropped.
+                    // Only an issue for PHP 5, this hack can be removed once PHP 5 support has been dropped.
                     $g = $f;
                     $f = $g;
                 });

src/LibEvLoop.php

@@ -39,7 +39,7 @@ function ($signal) {
                     $this->signals->call($signal);
                     // Ensure there are two copies of the callable around until it has been executed.
                     // For more information see: https://bugs.php.net/bug.php?id=62452
-                    // Only an issue for PHP 5, this hack can be removed once PHP 5 suppose has been dropped.
+                    // Only an issue for PHP 5, this hack can be removed once PHP 5 support has been dropped.
                     $g = $f;
                     $f = $g;
                 }, $signal);

src/LibEventLoop.php

@@ -43,7 +43,7 @@ function ($signal) {
                     $this->signals->call($signal);
                     // Ensure there are two copies of the callable around until it has been executed.
                     // For more information see: https://bugs.php.net/bug.php?id=62452
-                    // Only an issue for PHP 5, this hack can be removed once PHP 5 suppose has been dropped.
+                    // Only an issue for PHP 5, this hack can be removed once PHP 5 support has been dropped.
                     $g = $f;
                     $f = $g;
                 });

src/LoopInterface.php

@@ -152,14 +152,14 @@ public function removeWriteStream($stream);
      * can bind arbitrary data to a callback closure like this:
      *
      * ```php
-     * function hello(LoopInterface $loop, $name)
+     * function hello($name, LoopInterface $loop)
      * {
      *     $loop->addTimer(1.0, function () use ($name) {
      *         echo "hello $name\n";
      *     });
      * }
      *
-     * hello('Tester');
+     * hello('Tester', $loop);
      * ```
      *
      * The execution order of timers scheduled to execute at the same time is
@@ -205,7 +205,7 @@ public function addTimer($interval, callable $callback);
      * arbitrary data to a callback closure like this:
      *
      * ```php
-     * function hello(LoopInterface $loop, $name)
+     * function hello($name, LoopInterface $loop)
      * {
      *     $n = 3;
      *     $loop->addPeriodicTimer(1.0, function ($timer) use ($name, $loop, &$n) {
@@ -218,7 +218,7 @@ public function addTimer($interval, callable $callback);
      *     });
      * }
      *
-     * hello('Tester');
+     * hello('Tester', $loop);
      * ```
      *
      * The execution order of timers scheduled to execute at the same time is
@@ -237,12 +237,12 @@ public function addPeriodicTimer($interval, callable $callback);
      * See also [`addPeriodicTimer()`](#addperiodictimer) and [example #2](examples).
      *
      * You can use the [`isTimerActive()`](#istimeractive) method to check if
-     * this timer is still "active". After a timer is successfully canceled,
+     * this timer is still "active". After a timer is successfully cancelled,
      * it is no longer considered "active".
      *
      * Calling this method on a timer instance that has not been added to this
      * loop instance or on a timer that is not "active" (or has already been
-     * canceled) has no effect.
+     * cancelled) has no effect.
      *
      * @param TimerInterface $timer The timer to cancel.
      *
@@ -255,7 +255,7 @@ public function cancelTimer(TimerInterface $timer);
      *
      * A timer is considered "active" if it has been added to this loop instance
      * via [`addTimer()`](#addtimer) or [`addPeriodicTimer()`](#addperiodictimer)
-     * and has not been canceled via [`cancelTimer()`](#canceltimer) and is not
+     * and has not been cancelled via [`cancelTimer()`](#canceltimer) and is not
      * a non-periodic timer that has already been triggered after its interval.
      *
      * @param TimerInterface $timer The timer to check.
@@ -281,14 +281,14 @@ public function isTimerActive(TimerInterface $timer);
      * can bind arbitrary data to a callback closure like this:
      *
      * ```php
-     * function hello(LoopInterface $loop, $name)
+     * function hello($name, LoopInterface $loop)
      * {
      *     $loop->futureTick(function () use ($name) {
      *         echo "hello $name\n";
      *     });
      * }
      *
-     * hello('Tester');
+     * hello('Tester', $loop);
      * ```
      *
      * Unlike timers, tick callbacks are guaranteed to be executed in the order
@@ -317,32 +317,55 @@ public function isTimerActive(TimerInterface $timer);
     public function futureTick(callable $listener);
 
     /**
-     * Registers a signal listener with the loop, which
-     * on it's turn registers it with a signal handler
-     * suitable for the loop implementation.
+     * Register a listener to be notified when a signal has been caught by this process.
      *
-     * A listener can only be added once, any attempts
-     * to add it again will be ignored.
+     * This is useful to catch user interrupt signals or shutdown signals from
+     * tools like `supervisor` or `systemd`.
+     *
+     * The listener callback function MUST be able to accept a single parameter,
+     * the signal added by this method or you MAY use a function which
+     * has no parameters at all.
+     *
+     * The listener callback function MUST NOT throw an `Exception`.
+     * The return value of the listener callback function will be ignored and has
+     * no effect, so for performance reasons you're recommended to not return
+     * any excessive data structures.
+     *
+     * ```php
+     * $loop->addSignal(SIGINT, function (int $signal) {
+     *     echo 'Caught user interrupt signal' . PHP_EOL;
+     * });
+     * ```
      *
      * See also [example #4](examples).
      *
+     * Signaling is only available on Unix-like platform, Windows isn't
+     * supported due to operating system limitations.
+     * This method may throw a `BadMethodCallException` if signals aren't
+     * supported on this platform, for example when required extensions are
+     * missing.
+     *
+     * **Note: A listener can only be added once to the same signal, any
+     * attempts to add it more then once will be ignored.**
+     *
      * @param int $signal
      * @param callable $listener
      *
-     * @throws \BadMethodCallException when signals
-     * aren't supported by the loop, e.g. when required
-     * extensions are missing.
+     * @throws \BadMethodCallException when signals aren't supported on this
+     *     platform, for example when required extensions are missing.
      *
      * @return void
      */
     public function addSignal($signal, callable $listener);
 
     /**
-     * Removed previous registered signal listener from
-     * the loop, which on it's turn removes it from the
-     * underlying signal handler.
+     * Removes a previously added signal listener.
      *
-     * See also [example #4](examples).
+     * ```php
+     * $loop->removeSignal(SIGINT, $listener);
+     * ```
+     *
+     * Any attempts to remove listeners that aren't registered will be ignored.
      *
      * @param int $signal
      * @param callable $listener

src/StreamSelectLoop.php

@@ -37,7 +37,7 @@ function ($signal) {
                     $this->signals->call($signal);
                     // Ensure there are two copies of the callable around until it has been executed.
                     // For more information see: https://bugs.php.net/bug.php?id=62452
-                    // Only an issue for PHP 5, this hack can be removed once PHP 5 suppose has been dropped.
+                    // Only an issue for PHP 5, this hack can be removed once PHP 5 support has been dropped.
                     $g = $f;
                     $f = $g;
                 });

tests/AbstractLoopTest.php

@@ -72,8 +72,8 @@ public function testAddReadStreamReceivesDataFromStreamReference()
     }
 
     /**
-     * Telper for above test. This happens in another helper method to verify
-     * the loop keep track of assigned stream resources (refcount).
+     * Helper for above test. This happens in another helper method to verify
+     * the loop keeps track of assigned stream resources (refcount).
      */
     private function subAddReadStreamReceivesDataFromStreamReference()
     {