Improve documentation regarding deprecated Factory

Author: clue

README.md

@@ -13,30 +13,30 @@ single [`run()`](#run) call that is controlled by the user.
 
 * [Quickstart example](#quickstart-example)
 * [Usage](#usage)
-  * [Loop](#loop)
-    * [get()](#get)
-  * [Factory](#factory)
-    * [create()](#create)
-  * [Loop implementations](#loop-implementations)
-    * [StreamSelectLoop](#streamselectloop)
-    * [ExtEventLoop](#exteventloop)
-    * [ExtLibeventLoop](#extlibeventloop)
-    * [ExtLibevLoop](#extlibevloop)
-    * [ExtEvLoop](#extevloop)
-    * [ExtUvLoop](#extuvloop)
-  * [LoopInterface](#loopinterface)
-    * [run()](#run)
-    * [stop()](#stop)
-    * [addTimer()](#addtimer)
-    * [addPeriodicTimer()](#addperiodictimer)
-    * [cancelTimer()](#canceltimer)
-    * [futureTick()](#futuretick)
-    * [addSignal()](#addsignal)
-    * [removeSignal()](#removesignal)
-    * [addReadStream()](#addreadstream)
-    * [addWriteStream()](#addwritestream)
-    * [removeReadStream()](#removereadstream)
-    * [removeWriteStream()](#removewritestream)
+    * [Loop](#loop)
+        * [get()](#get)
+    * [Factory](#factory)
+        * [~~create()~~](#create)
+    * [Loop implementations](#loop-implementations)
+        * [StreamSelectLoop](#streamselectloop)
+        * [ExtEventLoop](#exteventloop)
+        * [ExtLibeventLoop](#extlibeventloop)
+        * [ExtLibevLoop](#extlibevloop)
+        * [ExtEvLoop](#extevloop)
+        * [ExtUvLoop](#extuvloop)
+    * [LoopInterface](#loopinterface)
+        * [run()](#run)
+        * [stop()](#stop)
+        * [addTimer()](#addtimer)
+        * [addPeriodicTimer()](#addperiodictimer)
+        * [cancelTimer()](#canceltimer)
+        * [futureTick()](#futuretick)
+        * [addSignal()](#addsignal)
+        * [removeSignal()](#removesignal)
+        * [addReadStream()](#addreadstream)
+        * [addWriteStream()](#addwritestream)
+        * [removeReadStream()](#removereadstream)
+        * [removeWriteStream()](#removewritestream)
 * [Install](#install)
 * [Tests](#tests)
 * [License](#license)
@@ -83,34 +83,29 @@ Typical applications use a single event loop which is created at the beginning
 and run at the end of the program.
 
 ```php
-// [1]
-$loop = React\EventLoop\Factory::create();
+$loop = React\EventLoop\Loop::get(); // or deprecated React\EventLoop\Factory::create();
 
-// [2]
-$loop->addPeriodicTimer(1, function () {
-    echo "Tick\n";
+$timer = $loop->addPeriodicTimer(0.1, function () {
+    echo "Tick" . PHP_EOL;
+});
+$loop->addTimer(1.0, function () use ($loop, $timer) {
+    $loop->cancelTimer($timer);
+    echo 'Done' . PHP_EOL;
 });
 
-$stream = new React\Stream\ReadableResourceStream(
-    fopen('file.txt', 'r'),
-    $loop
-);
-
-// [3]
 $loop->run();
 ```
 
-1. The loop instance is created at the beginning of the program. A convenience
-   factory [`React\EventLoop\Factory::create()`](#create) is provided by this library which
-   picks the best available [loop implementation](#loop-implementations).
-2. The loop instance is used directly or passed to library and application code.
-   In this example, a periodic timer is registered with the event loop which
-   simply outputs `Tick` every second and a
-   [readable stream](https://github.com/reactphp/stream#readableresourcestream)
-   is created by using ReactPHP's
-   [stream component](https://github.com/reactphp/stream) for demonstration
-   purposes.
-3. The loop is run with a single [`$loop->run()`](#run) call at the end of the program.
+1. The event loop instance is created at the beginning of the program. This is
+   implicitly done the first time you call the [`Loop` class](#loop) or
+   explicitly when using the deprecated [`Factory::create() method`](#create)
+   (or manually instantiating any of the [loop implementation](#loop-implementations)).
+2. The event loop is used directly or passed as an instance to library and
+   application code. In this example, a periodic timer is registered with the
+   event loop which simply outputs `Tick` every fraction of a second until another
+   timer stops the periodic timer after a second.
+3. The event loop is run at the end of the program with a single [`run()`](#run)
+   call at the end of the program.
 
 ### Loop
 
@@ -139,13 +134,17 @@ Loop::get()->run();
 The `Factory` class exists as a convenient way to pick the best available
 [event loop implementation](#loop-implementations).
 
-#### create()
+#### ~~create()~~
 
-The `create(): LoopInterface` method can be used to create a new event loop
-instance:
+The deprecated `create(): LoopInterface` method can be used to
+create a new event loop instance:
 
 ```php
+// deprecated
 $loop = React\EventLoop\Factory::create();
+
+// new
+$loop = React\EventLoop\Loop::get();
 ```
 
 This method always returns an instance implementing [`LoopInterface`](#loopinterface),

src/Factory.php

@@ -11,7 +11,11 @@ final class Factory
      * Creates a new event loop instance
      *
      * ```php
+     * // deprecated
      * $loop = React\EventLoop\Factory::create();
+     *
+     * // new
+     * $loop = React\EventLoop\Loop::get();
      * ```
      *
      * This method always returns an instance implementing `LoopInterface`,