Skip to content

Commit 9810645

Browse files
bwoebibwoebi
authored
Merge pull request #103 from async-interop/docs-formatting
Documentation formatting
2 parents 3244139 + 77764d5 commit 9810645

File tree

2 files changed

+88
-79
lines changed

2 files changed

+88
-79
lines changed

‎src/Loop.php‎

Lines changed: 46 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -32,11 +32,11 @@ final class Loop
3232
/**
3333
* Set the factory to be used to create a default drivers.
3434
*
35-
* Setting a factory is only allowed as long as no loop is currently running. Passing null will reset the default
36-
* driver and remove the factory.
35+
* Setting a factory is only allowed as long as no loop is currently running. Passing null will reset the
36+
* default driver and remove the factory.
3737
*
38-
* The factory will be invoked if none is passed to Loop::execute. A default driver will be created to support
39-
* synchronous waits in traditional applications.
38+
* The factory will be invoked if none is passed to `Loop::execute`. A default driver will be created to
39+
* support synchronous waits in traditional applications.
4040
*
4141
* @param DriverFactory|null $factory New factory to replace the previous one.
4242
*/
@@ -56,9 +56,11 @@ public static function setFactory(DriverFactory $factory = null)
5656
* Execute a callback within the scope of an event loop driver.
5757
*
5858
* @param callable $callback The callback to execute.
59-
* @param Driver $driver The event loop driver. If null a new one is created from the set factory.
59+
* @param Driver $driver The event loop driver. If `null`, a new one is created from the set factory.
6060
*
6161
* @return void
62+
*
63+
* @see \Interop\Async\Loop::setFactory()
6264
*/
6365
public static function execute(callable $callback, Driver $driver = null)
6466
{
@@ -79,19 +81,19 @@ public static function execute(callable $callback, Driver $driver = null)
7981
/**
8082
* Create a new driver if a factory is present, otherwise throw.
8183
*
82-
* @throws \LogicException If no factory is set or no driver returned from factory.
84+
* @throws \Exception If no factory is set or no driver returned from factory.
8385
*/
8486
private static function createDriver()
8587
{
8688
if (self::$factory === null) {
87-
throw new \LogicException("No loop driver factory set; Either pass a driver to Loop::execute or set a factory.");
89+
throw new \Exception("No loop driver factory set; Either pass a driver to Loop::execute or set a factory.");
8890
}
8991

9092
$driver = self::$factory->create();
9193

9294
if (!$driver instanceof Driver) {
9395
$type = is_object($driver) ? "an instance of " . get_class($driver) : gettype($driver);
94-
throw new \LogicException("Loop driver factory returned {$type}, but must return an instance of Driver.");
96+
throw new \Exception("Loop driver factory returned {$type}, but must return an instance of Driver.");
9597
}
9698

9799
return $driver;
@@ -126,7 +128,7 @@ public static function stop()
126128
* Defer the execution of a callback.
127129
*
128130
* @param callable(string $watcherId, mixed $data) $callback The callback to defer.
129-
* @param mixed $data Arbitrary data given to the callback function as the $data parameter.
131+
* @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
130132
*
131133
* @return string An identifier that can be used to cancel, enable or disable the watcher.
132134
*/
@@ -143,7 +145,7 @@ public static function defer(callable $callback, $data = null)
143145
*
144146
* @param int $time The amount of time, in milliseconds, to delay the execution for.
145147
* @param callable(string $watcherId, mixed $data) $callback The callback to delay.
146-
* @param mixed $data Arbitrary data given to the callback function as the $data parameter.
148+
* @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
147149
*
148150
* @return string An identifier that can be used to cancel, enable or disable the watcher.
149151
*/
@@ -161,7 +163,7 @@ public static function delay($time, callable $callback, $data = null)
161163
*
162164
* @param int $interval The time interval, in milliseconds, to wait between executions.
163165
* @param callable(string $watcherId, mixed $data) $callback The callback to repeat.
164-
* @param mixed $data Arbitrary data given to the callback function as the $data parameter.
166+
* @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
165167
*
166168
* @return string An identifier that can be used to cancel, enable or disable the watcher.
167169
*/
@@ -176,7 +178,7 @@ public static function repeat($interval, callable $callback, $data = null)
176178
*
177179
* @param resource $stream The stream to monitor.
178180
* @param callable(string $watcherId, resource $stream, mixed $data) $callback The callback to execute.
179-
* @param mixed $data Arbitrary data given to the callback function as the $data parameter.
181+
* @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
180182
*
181183
* @return string An identifier that can be used to cancel, enable or disable the watcher.
182184
*/
@@ -191,7 +193,7 @@ public static function onReadable($stream, callable $callback, $data = null)
191193
*
192194
* @param resource $stream The stream to monitor.
193195
* @param callable(string $watcherId, resource $stream, mixed $data) $callback The callback to execute.
194-
* @param mixed $data Arbitrary data given to the callback function as the $data parameter.
196+
* @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
195197
*
196198
* @return string An identifier that can be used to cancel, enable or disable the watcher.
197199
*/
@@ -205,11 +207,11 @@ public static function onWritable($stream, callable $callback, $data = null)
205207
* Execute a callback when a signal is received.
206208
*
207209
* WARNING: Installing a handler on the same signal on different scopes of event loop execution is
208-
* undefined behavior and may break things arbitrarily.
210+
* undefined behavior and may break things arbitrarily.
209211
*
210212
* @param int $signo The signal number to monitor.
211213
* @param callable(string $watcherId, int $signo, mixed $data) $callback The callback to execute.
212-
* @param mixed $data Arbitrary data given to the callback function as the $data parameter.
214+
* @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
213215
*
214216
* @return string An identifier that can be used to cancel, enable or disable the watcher.
215217
*
@@ -250,8 +252,10 @@ public static function disable($watcherId)
250252
}
251253

252254
/**
253-
* Cancel a watcher. This will detatch the event loop from all resources that are associated to the watcher. After
254-
* this operation the watcher is permanently invalid.
255+
* Cancel a watcher.
256+
*
257+
* This will detatch the event loop from all resources that are associated to the watcher. After this
258+
* operation the watcher is permanently invalid.
255259
*
256260
* @param string $watcherId The watcher identifier.
257261
*
@@ -266,8 +270,8 @@ public static function cancel($watcherId)
266270
/**
267271
* Reference a watcher.
268272
*
269-
* This will keep the event loop alive whilst the watcher is still being monitored. Watchers have this state by
270-
* default.
273+
* This will keep the event loop alive whilst the watcher is still being monitored. Watchers have this state
274+
* by default.
271275
*
272276
* @param string $watcherId The watcher identifier.
273277
*
@@ -284,8 +288,8 @@ public static function reference($watcherId)
284288
/**
285289
* Unreference a watcher.
286290
*
287-
* The event loop should exit the run method when only unreferenced watchers are still being monitored. Watchers
288-
* are all referenced by default.
291+
* The event loop should exit the run method when only unreferenced watchers are still being monitored.
292+
* Watchers are all referenced by default.
289293
*
290294
* @param string $watcherId The watcher identifier.
291295
*
@@ -300,13 +304,14 @@ public static function unreference($watcherId)
300304
}
301305

302306
/**
303-
* Stores information in the loop bound registry. This can be used to store loop bound information. Stored
304-
* information is package private. Packages MUST NOT retrieve the stored state of other packages.
307+
* Stores information in the loop bound registry.
305308
*
306-
* Therefore packages SHOULD use the following prefix to keys: `vendor.package.`
309+
* This can be used to store loop bound information. Stored information is package private. Packages MUST NOT
310+
* retrieve the stored state of other packages. Packages MUST use the following prefix to keys:
311+
* `vendor.package.`
307312
*
308-
* @param string $key namespaced storage key
309-
* @param mixed $value the value to be stored
313+
* @param string $key The namespaced storage key.
314+
* @param mixed $value The value to be stored.
310315
*
311316
* @return void
312317
*/
@@ -317,12 +322,12 @@ public static function setState($key, $value)
317322
}
318323

319324
/**
320-
* Gets information stored bound to the loop. Stored information is package private. Packages MUST NOT retrieve the
321-
* stored state of other packages.
325+
* Gets information stored bound to the loop.
322326
*
323-
* Therefore packages SHOULD use the following prefix to keys: `vendor.package.`
327+
* Stored information is package private. Packages MUST NOT retrieve the stored state of other packages.
328+
* Packages MUST use the following prefix to keys: `vendor.package.`
324329
*
325-
* @param string $key namespaced storage key
330+
* @param string $key The namespaced storage key.
326331
*
327332
* @return mixed previously stored value or null if it doesn't exist
328333
*/
@@ -353,17 +358,17 @@ public static function setErrorHandler(callable $callback = null)
353358
*
354359
* The returned array MUST contain the following data describing the driver's currently registered watchers:
355360
*
356-
* [
357-
* "defer" => ["enabled" => int, "disabled" => int],
358-
* "delay" => ["enabled" => int, "disabled" => int],
359-
* "repeat" => ["enabled" => int, "disabled" => int],
360-
* "on_readable" => ["enabled" => int, "disabled" => int],
361-
* "on_writable" => ["enabled" => int, "disabled" => int],
362-
* "on_signal" => ["enabled" => int, "disabled" => int],
363-
* "watchers" => ["referenced" => int, "unreferenced" => int],
364-
* ];
365-
*
366-
* Implementations MAY optionally add more information in the array but at minimum the above key => value format
361+
* [
362+
* "defer" => ["enabled" => int, "disabled" => int],
363+
* "delay" => ["enabled" => int, "disabled" => int],
364+
* "repeat" => ["enabled" => int, "disabled" => int],
365+
* "on_readable" => ["enabled" => int, "disabled" => int],
366+
* "on_writable" => ["enabled" => int, "disabled" => int],
367+
* "on_signal" => ["enabled" => int, "disabled" => int],
368+
* "watchers" => ["referenced" => int, "unreferenced" => int],
369+
* ];
370+
*
371+
* Implementations MAY optionally add more information in the array but at minimum the above `key => value` format
367372
* MUST always be provided.
368373
*
369374
* @return array

0 commit comments

Comments
 (0)