Mark stream API as advanced and link to Stream component instead

clue · clue · commit 753c911d099d · 2017-10-13T15:32:37.000+02:00
diff --git a/README.md b/README.md
@@ -22,6 +22,7 @@ For the code of the current stable 0.4.x release, checkout the
 * [Install](#install)
 * [Tests](#tests)
 * [License](#license)
+* [More](#more)
 
 ## Quickstart example
 
@@ -293,6 +294,11 @@ See also [example #3](examples).
 
 ### addReadStream()
 
+> Advanced! Note that this low-level API is considered advanced usage.
+  Most use cases should probably use the higher-level
+  [readable Stream API](https://github.com/reactphp/stream#readablestreaminterface)
+  instead.
+
 The `addReadStream(resource $stream, callable $callback): void` method can be used to
 register a listener to be notified when a stream is ready to read.
 
@@ -331,6 +337,11 @@ the same time is not guaranteed.
 
 ### addWriteStream()
 
+> Advanced! Note that this low-level API is considered advanced usage.
+  Most use cases should probably use the higher-level
+  [writable Stream API](https://github.com/reactphp/stream#writablestreaminterface)
+  instead.
+
 The `addWriteStream(resource $stream, callable $callback): void` method can be used to
 register a listener to be notified when a stream is ready to write.
 
@@ -420,3 +431,11 @@ $ php vendor/bin/phpunit
 ## License
 
 MIT, see [LICENSE file](LICENSE).
+
+## More
+
+* See our [Stream component](https://github.com/reactphp/stream) for more
+  information on how streams are used in real-world applications.
+* See our [users wiki](https://github.com/reactphp/react/wiki/Users) and the
+  [dependents on Packagist](https://packagist.org/packages/react/event-loop/dependents)
+  for a list of packages that use the EventLoop in real-world applications.
diff --git a/src/LoopInterface.php b/src/LoopInterface.php
@@ -7,7 +7,12 @@
 interface LoopInterface
 {
     /**
-     * Register a listener to be notified when a stream is ready to read.
+     * [Advanced] Register a listener to be notified when a stream is ready to read.
+     *
+     * Note that this low-level API is considered advanced usage.
+     * Most use cases should probably use the higher-level
+     * [readable Stream API](https://github.com/reactphp/stream#readablestreaminterface)
+     * instead.
      *
      * The first parameter MUST be a valid stream resource that supports
      * checking whether it is ready to read by this loop implementation.
@@ -49,7 +54,12 @@ interface LoopInterface
     public function addReadStream($stream, callable $listener);
 
     /**
-     * Register a listener to be notified when a stream is ready to write.
+     * [Advanced] Register a listener to be notified when a stream is ready to write.
+     *
+     * Note that this low-level API is considered advanced usage.
+     * Most use cases should probably use the higher-level
+     * [writable Stream API](https://github.com/reactphp/stream#writablestreaminterface)
+     * instead.
      *
      * The first parameter MUST be a valid stream resource that supports
      * checking whether it is ready to write by this loop implementation.
