From d431fa7d420e05757a4eaf47e19a76480e40a0fa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christian=20L=C3=BCck?= <christian@lueck.tv>
Date: Sun, 3 Dec 2017 16:41:29 +0100
Subject: [PATCH] Update signal handling documentation

---
 README.md             | 32 +++++++++++++++--------------
 src/LoopInterface.php | 47 ++++++++++++++++++++++++++++++++-----------
 2 files changed, 52 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index c3ee54a3..d98e4c73 100644
--- a/README.md
+++ b/README.md
@@ -313,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
@@ -326,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()
 
diff --git a/src/LoopInterface.php b/src/LoopInterface.php
index cf074ca0..57783fab 100644
--- a/src/LoopInterface.php
+++ b/src/LoopInterface.php
@@ -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