API doc request: provide example of consuming a Stream in tokio::stream or tokio::stream::Stream API docs.

[nathan-at-least]

Version

Declared dependency: tokio = { version = "=0.2.0-alpha.6", features = ["process"] }

$ cargo tree | grep tokio
└── tokio v0.2.0-alpha.6
    ├── tokio-codec v0.2.0-alpha.6
    │   └── tokio-io v0.2.0-alpha.6
    ├── tokio-executor v0.2.0-alpha.6
    │   ├── tokio-sync v0.2.0-alpha.6
    ├── tokio-fs v0.2.0-alpha.6
    │   ├── tokio-executor v0.2.0-alpha.6 (*)
    │   ├── tokio-io v0.2.0-alpha.6 (*)
    │   └── tokio-sync v0.2.0-alpha.6 (*)
    ├── tokio-io v0.2.0-alpha.6 (*)
    ├── tokio-macros v0.2.0-alpha.6
    ├── tokio-net v0.2.0-alpha.6
    │   ├── tokio-codec v0.2.0-alpha.6 (*)
    │   ├── tokio-executor v0.2.0-alpha.6 (*)
    │   ├── tokio-io v0.2.0-alpha.6 (*)
    │   ├── tokio-sync v0.2.0-alpha.6 (*)
    ├── tokio-sync v0.2.0-alpha.6 (*)
    ├── tokio-timer v0.3.0-alpha.6
    │   ├── tokio-executor v0.2.0-alpha.6 (*)
    │   └── tokio-sync v0.2.0-alpha.6 (*)

Platform

$ uname -a
Linux penguin 4.19.69-06666-g6c4f8cbba24e #1 SMP PREEMPT Fri Sep 6 22:15:24 PDT 2019 x86_64 GNU/Linux

Description

Summary: Include an example of how to consume a Stream in its API docs.

I am also somewhat confused about the relationship between tokio's async abstractions and the std or core abstractions. I realize some things are re-exported, whereas others may be extended/customized. Due to that confusion I decided to file this ticket here, since I'm not sure if the examples I'm requesting would require tokio-specific dependencies. If this issue is better filed with the core API doc codebase, let me know and I'm happy to pursue that in the appropriate issue tracker.

I'm learning tokio and async/await by primarily focusing on API docs rather than guides/blog posts due to the significant API churn. (Many blogs/guides might use older APIs.)

While doing so, I understand how to use x.await where the type of x impls Future. However, I haven't yet been able to learn the equivalent way to consume a Stream value.

The API doc improvement request is to include examples of consuming Stream. While we're at it, examples of consuming Future and AsyncRead would be helpful at the trait-level documentation.

From conversation with a more experienced rust dev friend it sounds like most code will potentially use blanket-extension traits (ex StreamExt). I suggest including realistic examples of consuming the extension trait in the docs of the base trait.

How I got here:

I am learning tokio with a first project that multiplexes stdout/stderr from multiple child processes (dev/test on linux for now).

I am primarily following API docs, because when I google and see blog posts or guides, I am never clear which version of the (significantly shifting) APIs they use. My goal is to learn the upcoming tokio + async/await framework without getting bogged down in the 0.1.0 tokio series or the era of many crates.

Related: #1738

[carllerche]

This should be handled by tokio.rs/tokio/tutorial/streams