Improve documentation regarding deprecated Factory

Author: clue

README.md

@@ -13,31 +13,31 @@ single [`run()`](#run) call that is controlled by the user.
 
 * [Quickstart example](#quickstart-example)
 * [Usage](#usage)
-  * [Loop](#loop)
-    * [Loop methods](#loop-methods)
-    * [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)
+        * [Loop methods](#loop-methods)
+        * [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)
@@ -262,18 +262,26 @@ Loop::run();
 
 See [`LoopInterface`](#loopinterface) for more details about available methods.
 
-### Factory
+### ~~Factory~~
 
-The `Factory` class exists as a convenient way to pick the best available
+> Deprecated since v1.2.0, see [`Loop` class](#loop) instead.
+
+The deprecated `Factory` class exists as a convenient way to pick the best available
 [event loop implementation](#loop-implementations).
 
-#### create()
+#### ~~create()~~
+
+> Deprecated since v1.2.0, see [`Loop::get()`](#get) instead.
 
-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

@@ -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
      */