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)
@@ -84,7 +84,7 @@ 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 () {
@@ -100,9 +100,10 @@ $stream = new React\Stream\ReadableResourceStream(
 $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).
+1. The 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 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
@@ -134,18 +135,26 @@ Loop::get()->addTimer(0.01, function () {
 Loop::get()->run();
 ```
 
-### Factory
+### ~~Factory~~
+
+> Deprecated since v1.2.0, see [`Loop` class](#loop) instead.
 
-The `Factory` class exists as a convenient way to pick the best available
+The deprecated `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:
+> Deprecated since v1.2.0, see [`Loop::get()`](#get) instead.
+
+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

@@ -3,23 +3,31 @@
 namespace React\EventLoop;
 
 /**
- * The `Factory` class exists as a convenient way to pick the best available event loop implementation.
+ * [Deprecated] The `Factory` class exists as a convenient way to pick the best available event loop implementation.
+ *
+ * @deprecated 1.2.0 See Loop instead.
+ * @see Loop
  */
 final class Factory
 {
     /**
-     * Creates a new event loop instance
+     * [Deprecated] 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`,
      * the actual event loop implementation is an implementation detail.
      *
      * This method should usually only be called once at the beginning of the program.
      *
-     * @deprecated Use Loop::get instead
+     * @deprecated 1.2.0 See Loop::get() instead.
+     * @see Loop::get()
      *
      * @return LoopInterface
      */