Merge pull request #119 from clue-labs/factory-documentation

Documentation for Factory
reactphp · Nov 10, 2017 · 49ac483 · 49ac483
2 parents f94c3ea + f4e9322
commit 49ac483
Show file tree

Hide file tree

Showing 7 changed files with 34 additions and 166 deletions.
diff --git a/README.md b/README.md
@@ -94,6 +94,23 @@ $loop->run();
    purposes.
 3. The loop is run with a single `$loop->run()` call at the end of the program.
 
+## Factory
+
+The `Factory` class exists as a convenient way to pick the best available
+[loop implementation)(#loop-implementation).
+
+The `create(): LoopInterface` method can be used to create a new loop
+instance:
+
+```php
+$loop = React\EventLoop\Factory::create();
+```
+
+This method always returns an instance implementing `LoopInterface`,
+the actual loop implementation is an implementation detail.
+
+This method should usually only be called once at the beginning of the program.
+
 ## Loop implementations
 
 In addition to the interface there are the following implementations provided:

diff --git a/src/ExtEventLoop.php b/src/ExtEventLoop.php
@@ -59,9 +59,6 @@ function ($signal) {
         $this->createStreamCallback();
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function addReadStream($stream, callable $listener)
     {
         $key = (int) $stream;
@@ -72,9 +69,6 @@ public function addReadStream($stream, callable $listener)
         }
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function addWriteStream($stream, callable $listener)
     {
         $key = (int) $stream;
@@ -85,9 +79,6 @@ public function addWriteStream($stream, callable $listener)
         }
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function removeReadStream($stream)
     {
         $key = (int) $stream;
@@ -98,9 +89,6 @@ public function removeReadStream($stream)
         }
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function removeWriteStream($stream)
     {
         $key = (int) $stream;
@@ -127,9 +115,6 @@ private function removeStream($stream)
         }
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function addTimer($interval, callable $callback)
     {
         $timer = new Timer($interval, $callback, false);
@@ -139,9 +124,6 @@ public function addTimer($interval, callable $callback)
         return $timer;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function addPeriodicTimer($interval, callable $callback)
     {
         $timer = new Timer($interval, $callback, true);
@@ -151,9 +133,6 @@ public function addPeriodicTimer($interval, callable $callback)
         return $timer;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function cancelTimer(TimerInterface $timer)
     {
         if ($this->isTimerActive($timer)) {
@@ -162,41 +141,26 @@ public function cancelTimer(TimerInterface $timer)
         }
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function isTimerActive(TimerInterface $timer)
     {
         return $this->timerEvents->contains($timer);
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function futureTick(callable $listener)
     {
         $this->futureTickQueue->add($listener);
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function addSignal($signal, callable $listener)
     {
         $this->signals->add($signal, $listener);
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function removeSignal($signal, callable $listener)
     {
         $this->signals->remove($signal, $listener);
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function run()
     {
         $this->running = true;
@@ -215,9 +179,6 @@ public function run()
         }
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function stop()
     {
         $this->running = false;

diff --git a/src/Factory.php b/src/Factory.php
@@ -2,8 +2,25 @@
 
 namespace React\EventLoop;
 
+/**
+ * The `Factory` class exists as a convenient way to pick the best available loop implementation.
+ */
 class Factory
 {
+    /**
+     * Creates a new loop instance
+     *
+     * ```php
+     * $loop = React\EventLoop\Factory::create();
+     * ```
+     *
+     * This method always returns an instance implementing `LoopInterface`,
+     * the actual loop implementation is an implementation detail.
+     *
+     * This method should usually only be called once at the beginning of the program.
+     *
+     * @return LoopInterface
+     */
     public static function create()
     {
         // @codeCoverageIgnoreStart

diff --git a/src/LibEvLoop.php b/src/LibEvLoop.php
@@ -54,9 +54,6 @@ function ($signal) {
         );
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function addReadStream($stream, callable $listener)
     {
         if (isset($this->readEvents[(int) $stream])) {
@@ -73,9 +70,6 @@ public function addReadStream($stream, callable $listener)
         $this->readEvents[(int) $stream] = $event;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function addWriteStream($stream, callable $listener)
     {
         if (isset($this->writeEvents[(int) $stream])) {
@@ -92,9 +86,6 @@ public function addWriteStream($stream, callable $listener)
         $this->writeEvents[(int) $stream] = $event;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function removeReadStream($stream)
     {
         $key = (int) $stream;
@@ -105,9 +96,6 @@ public function removeReadStream($stream)
         }
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function removeWriteStream($stream)
     {
         $key = (int) $stream;
@@ -118,9 +106,6 @@ public function removeWriteStream($stream)
         }
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function addTimer($interval, callable $callback)
     {
         $timer = new Timer( $interval, $callback, false);
@@ -140,9 +125,6 @@ public function addTimer($interval, callable $callback)
         return $timer;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function addPeriodicTimer($interval, callable $callback)
     {
         $timer = new Timer($interval, $callback, true);
@@ -158,9 +140,6 @@ public function addPeriodicTimer($interval, callable $callback)
         return $timer;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function cancelTimer(TimerInterface $timer)
     {
         if (isset($this->timerEvents[$timer])) {
@@ -169,41 +148,26 @@ public function cancelTimer(TimerInterface $timer)
         }
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function isTimerActive(TimerInterface $timer)
     {
         return $this->timerEvents->contains($timer);
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function futureTick(callable $listener)
     {
         $this->futureTickQueue->add($listener);
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function addSignal($signal, callable $listener)
     {
         $this->signals->add($signal, $listener);
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function removeSignal($signal, callable $listener)
     {
         $this->signals->remove($signal, $listener);
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function run()
     {
         $this->running = true;
@@ -222,9 +186,6 @@ public function run()
         }
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function stop()
     {
         $this->running = false;