Improve documentation regarding deprecated Factory

clue · clue · commit c006e3c2e489 · 2021-06-30T09:51:06.000+02:00
diff --git a/README.md b/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 implementations](#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),
diff --git a/src/Factory.php b/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
      */

Original file line number	Diff line number	Diff line change
`@@ -3,23 +3,31 @@`
`3`	`3`	`namespace React\EventLoop;`
`4`	`4`
`5`	`5`	`/**`
`6`		- * The `Factory` class exists as a convenient way to pick the best available event loop implementation.
	`6`	+ * [Deprecated] The `Factory` class exists as a convenient way to pick the best available event loop implementation.
	`7`	`+ *`
	`8`	`+ * @deprecated 1.2.0 See Loop instead.`
	`9`	`+ * @see Loop`
`7`	`10`	`*/`
`8`	`11`	`final class Factory`
`9`	`12`	`{`
`10`	`13`	`/**`
`11`		`- * Creates a new event loop instance`
	`14`	`+ * [Deprecated] Creates a new event loop instance`
`12`	`15`	`*`
`13`	`16`	* ```php
	`17`	`+ * // deprecated`
`14`	`18`	`* $loop = React\EventLoop\Factory::create();`
	`19`	`+ *`
	`20`	`+ * // new`
	`21`	`+ * $loop = React\EventLoop\Loop::get();`
`15`	`22`	* ```
`16`	`23`	`*`
`17`	`24`	* This method always returns an instance implementing `LoopInterface`,
`18`	`25`	`* the actual event loop implementation is an implementation detail.`
`19`	`26`	`*`
`20`	`27`	`* This method should usually only be called once at the beginning of the program.`
`21`	`28`	`*`
`22`		`- * @deprecated Use Loop::get instead`
	`29`	`+ * @deprecated 1.2.0 See Loop::get() instead.`
	`30`	`+ * @see Loop::get()`
`23`	`31`	`*`
`24`	`32`	`* @return LoopInterface`
`25`	`33`	`*/`