Document for await syntax (#45)

* Document for await syntax
* Make `README.md` a symlink to `async-stream/README.md`

Author: Kestrer

README.md

@@ -0,0 +1 @@
+async-stream/README.md

README.md

@@ -68,7 +68,8 @@ async fn main() {
 }
 ```
 
-Streams may be implemented in terms of other streams:
+Streams may be implemented in terms of other streams - `async-stream` provides `for await`
+syntax to assist with this:
 
 ```rust
 use async_stream::stream;
@@ -89,8 +90,7 @@ fn double<S: Stream<Item = u32>>(input: S)
     -> impl Stream<Item = u32>
 {
     stream! {
-        pin_mut!(input);
-        while let Some(value) = input.next().await {
+        for await value in input {
             yield value * 2;
         }
     }
@@ -124,7 +124,7 @@ fn bind_and_accept(addr: SocketAddr)
     -> impl Stream<Item = io::Result<TcpStream>>
 {
     try_stream! {
-        let mut listener = TcpListener::bind(&addr)?;
+        let mut listener = TcpListener::bind(addr).await?;
 
         loop {
             let (stream, addr) = listener.accept().await?;
@@ -148,17 +148,7 @@ stored on the stack. A pointer to the cell is stored in a thread local and
 `sender.send(value)` stores the value that cell and yields back to the
 caller.
 
-## Limitations
-
-`async-stream` suffers from the same limitations as the [`proc-macro-hack`]
-crate. Primarily, nesting support must be implemented using a `TT-muncher`.
-If large `stream!` blocks are used, the caller will be required to add
-`#![recursion_limit = "..."]` to their crate.
-
-A `stream!` macro may only contain up to 64 macro invocations.
-
 [`Stream`]: https://docs.rs/futures-core/*/futures_core/stream/trait.Stream.html
-[`proc-macro-hack`]: https://github.com/dtolnay/proc-macro-hack/
 
 ## License
 

async-stream/README.md

@@ -75,7 +75,8 @@
 //! }
 //! ```
 //!
-//! Streams may be implemented in terms of other streams:
+//! Streams may be implemented in terms of other streams - `async-stream` provides `for await`
+//! syntax to assist with this:
 //!
 //! ```rust
 //! use async_stream::stream;
@@ -96,8 +97,7 @@
 //!     -> impl Stream<Item = u32>
 //! {
 //!     stream! {
-//!         pin_mut!(input);
-//!         while let Some(value) = input.next().await {
+//!         for await value in input {
 //!             yield value * 2;
 //!         }
 //!     }