Merge pull request #394 from async-rs/link-types

backreference links for structs

src/io/empty.rs

@@ -28,9 +28,10 @@ pub fn empty() -> Empty {
 
 /// A reader that contains no data.
 ///
-/// This reader is constructed by the [`sink`] function.
+/// This reader is created by the [`empty`] function. See its
+/// documentation for more.
 ///
-/// [`sink`]: fn.sink.html
+/// [`empty`]: fn.empty.html
 pub struct Empty {
     _private: (),
 }

src/io/repeat.rs

@@ -29,7 +29,8 @@ pub fn repeat(byte: u8) -> Repeat {
 
 /// A reader which yields one byte over and over and over and over and over and...
 ///
-/// This reader is constructed by the [`repeat`] function.
+/// This reader is created by the [`repeat`] function. See its
+/// documentation for more.
 ///
 /// [`repeat`]: fn.repeat.html
 pub struct Repeat {

src/io/sink.rs

@@ -25,7 +25,8 @@ pub fn sink() -> Sink {
 
 /// A writer that consumes and drops all data.
 ///
-/// This writer is constructed by the [`sink`] function.
+/// This writer is constructed by the [`sink`] function. See its documentation
+/// for more.
 ///
 /// [`sink`]: fn.sink.html
 pub struct Sink {

src/io/stderr.rs

@@ -11,6 +11,12 @@ use crate::task::{blocking, Context, JoinHandle, Poll};
 ///
 /// [`std::io::stderr`]: https://doc.rust-lang.org/std/io/fn.stderr.html
 ///
+/// ### Note: Windows Portability Consideration
+///
+/// When operating in a console, the Windows implementation of this stream does not support
+/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
+/// an error.
+///
 /// # Examples
 ///
 /// ```no_run
@@ -34,12 +40,16 @@ pub fn stderr() -> Stderr {
 
 /// A handle to the standard error of the current process.
 ///
-/// Created by the [`stderr`] function.
+/// This writer is created by the [`stderr`] function. See its documentation for
+/// more.
 ///
-/// This type is an async version of [`std::io::Stderr`].
+/// ### Note: Windows Portability Consideration
+///
+/// When operating in a console, the Windows implementation of this stream does not support
+/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
+/// an error.
 ///
 /// [`stderr`]: fn.stderr.html
-/// [`std::io::Stderr`]: https://doc.rust-lang.org/std/io/struct.Stderr.html
 #[derive(Debug)]
 pub struct Stderr(Mutex<State>);
 

src/io/stdin.rs

@@ -11,6 +11,12 @@ use crate::task::{blocking, Context, JoinHandle, Poll};
 ///
 /// [`std::io::stdin`]: https://doc.rust-lang.org/std/io/fn.stdin.html
 ///
+/// ### Note: Windows Portability Consideration
+///
+/// When operating in a console, the Windows implementation of this stream does not support
+/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
+/// an error.
+///
 /// # Examples
 ///
 /// ```no_run
@@ -35,12 +41,16 @@ pub fn stdin() -> Stdin {
 
 /// A handle to the standard input of the current process.
 ///
-/// Created by the [`stdin`] function.
+/// This reader is created by the [`stdin`] function. See its documentation for
+/// more.
 ///
-/// This type is an async version of [`std::io::Stdin`].
+/// ### Note: Windows Portability Consideration
+///
+/// When operating in a console, the Windows implementation of this stream does not support
+/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
+/// an error.
 ///
 /// [`stdin`]: fn.stdin.html
-/// [`std::io::Stdin`]: https://doc.rust-lang.org/std/io/struct.Stdin.html
 #[derive(Debug)]
 pub struct Stdin(Mutex<State>);
 

src/io/stdout.rs

@@ -11,6 +11,12 @@ use crate::task::{blocking, Context, JoinHandle, Poll};
 ///
 /// [`std::io::stdout`]: https://doc.rust-lang.org/std/io/fn.stdout.html
 ///
+/// ### Note: Windows Portability Consideration
+///
+/// When operating in a console, the Windows implementation of this stream does not support
+/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
+/// an error.
+///
 /// # Examples
 ///
 /// ```no_run
@@ -34,12 +40,16 @@ pub fn stdout() -> Stdout {
 
 /// A handle to the standard output of the current process.
 ///
-/// Created by the [`stdout`] function.
+/// This writer is created by the [`stdout`] function. See its documentation
+/// for more.
 ///
-/// This type is an async version of [`std::io::Stdout`].
+/// ### Note: Windows Portability Consideration
+///
+/// When operating in a console, the Windows implementation of this stream does not support
+/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return
+/// an error.
 ///
 /// [`stdout`]: fn.stdout.html
-/// [`std::io::Stdout`]: https://doc.rust-lang.org/std/io/struct.Stdout.html
 #[derive(Debug)]
 pub struct Stdout(Mutex<State>);
 

src/stream/empty.rs

@@ -6,6 +6,11 @@ use crate::task::{Context, Poll};
 
 /// Creates a stream that doesn't yield any items.
 ///
+/// This `struct` is created by the [`empty`] function. See its
+/// documentation for more.
+///
+/// [`empty`]: fn.empty.html
+///
 /// # Examples
 ///
 /// ```

src/stream/from_fn.rs

@@ -10,7 +10,8 @@ use crate::task::{Context, Poll};
 pin_project! {
     /// A stream that yields elements by calling a closure.
     ///
-    /// This stream is constructed by [`from_fn`] function.
+    /// This stream is created by the [`from_fn`] function. See its
+    /// documentation for more.
     ///
     /// [`from_fn`]: fn.from_fn.html
     #[derive(Debug)]

src/stream/interval.rs

@@ -52,6 +52,10 @@ pub fn interval(dur: Duration) -> Interval {
 
 /// A stream representing notifications at fixed interval
 ///
+/// This stream is created by the [`interval`] function. See its
+/// documentation for more.
+///
+/// [`interval`]: fn.interval.html
 #[cfg(feature = "unstable")]
 #[cfg_attr(feature = "docs", doc(cfg(unstable)))]
 #[derive(Debug)]

src/stream/once.rs

@@ -29,7 +29,8 @@ pub fn once<T>(t: T) -> Once<T> {
 pin_project! {
     /// A stream that yields a single item.
     ///
-    /// This stream is constructed by the [`once`] function.
+    /// This stream is created by the [`once`] function. See its
+    /// documentation for more.
     ///
     /// [`once`]: fn.once.html
     #[derive(Debug)]

src/stream/repeat.rs

@@ -29,7 +29,8 @@ where
 
 /// A stream that yields the same item repeatedly.
 ///
-/// This stream is constructed by the [`repeat`] function.
+/// This stream is created by the [`repeat`] function. See its
+/// documentation for more.
 ///
 /// [`repeat`]: fn.repeat.html
 #[derive(Debug)]

src/stream/repeat_with.rs

@@ -10,7 +10,8 @@ use crate::task::{Context, Poll};
 pin_project! {
     /// A stream that repeats elements of type `T` endlessly by applying a provided closure.
     ///
-    /// This stream is constructed by the [`repeat_with`] function.
+    /// This stream is created by the [`repeat_with`] function. See its
+    /// documentation for more.
     ///
     /// [`repeat_with`]: fn.repeat_with.html
     #[derive(Debug)]

src/stream/stream/chain.rs

@@ -8,6 +8,12 @@ use crate::task::{Context, Poll};
 
 pin_project! {
     /// Chains two streams one after another.
+    ///
+    /// This `struct` is created by the [`chain`] method on [`Stream`]. See its
+    /// documentation for more.
+    ///
+    /// [`chain`]: trait.Stream.html#method.chain
+    /// [`Stream`]: trait.Stream.html
     #[derive(Debug)]
     pub struct Chain<S, U> {
         #[pin]

src/stream/stream/filter.rs

@@ -8,6 +8,12 @@ use crate::task::{Context, Poll};
 
 pin_project! {
     /// A stream to filter elements of another stream with a predicate.
+    ///
+    /// This `struct` is created by the [`filter`] method on [`Stream`]. See its
+    /// documentation for more.
+    ///
+    /// [`filter`]: trait.Stream.html#method.filter
+    /// [`Stream`]: trait.Stream.html
     #[derive(Debug)]
     pub struct Filter<S, P, T> {
         #[pin]

src/stream/stream/fuse.rs

@@ -8,6 +8,12 @@ use crate::task::{Context, Poll};
 pin_project! {
     /// A `Stream` that is permanently closed once a single call to `poll` results in
     /// `Poll::Ready(None)`, returning `Poll::Ready(None)` for all future calls to `poll`.
+    ///
+    /// This `struct` is created by the [`fuse`] method on [`Stream`]. See its
+    /// documentation for more.
+    ///
+    /// [`fuse`]: trait.Stream.html#method.fuse
+    /// [`Stream`]: trait.Stream.html
     #[derive(Clone, Debug)]
     pub struct Fuse<S> {
         #[pin]

src/stream/stream/inspect.rs

@@ -8,6 +8,12 @@ use crate::task::{Context, Poll};
 
 pin_project! {
     /// A stream that does something with each element of another stream.
+    ///
+    /// This `struct` is created by the [`inspect`] method on [`Stream`]. See its
+    /// documentation for more.
+    ///
+    /// [`inspect`]: trait.Stream.html#method.inspect
+    /// [`Stream`]: trait.Stream.html
     #[derive(Debug)]
     pub struct Inspect<S, F, T> {
         #[pin]

src/stream/stream/merge.rs

@@ -7,9 +7,11 @@ use pin_project_lite::pin_project;
 pin_project! {
     /// A stream that merges two other streams into a single stream.
     ///
-    /// This stream is returned by [`Stream::merge`].
+    /// This `struct` is created by the [`merge`] method on [`Stream`]. See its
+    /// documentation for more.
     ///
-    /// [`Stream::merge`]: trait.Stream.html#method.merge
+    /// [`merge`]: trait.Stream.html#method.merge
+    /// [`Stream`]: trait.Stream.html
     #[cfg(feature = "unstable")]
     #[cfg_attr(feature = "docs", doc(cfg(unstable)))]
     #[derive(Debug)]

src/stream/stream/scan.rs

@@ -7,6 +7,12 @@ use crate::task::{Context, Poll};
 
 pin_project! {
     /// A stream to maintain state while polling another stream.
+    ///
+    /// This `struct` is created by the [`scan`] method on [`Stream`]. See its
+    /// documentation for more.
+    ///
+    /// [`scan`]: trait.Stream.html#method.scan
+    /// [`Stream`]: trait.Stream.html
     #[derive(Debug)]
     pub struct Scan<S, St, F> {
         #[pin]

src/stream/stream/skip.rs

@@ -7,6 +7,12 @@ use crate::stream::Stream;
 
 pin_project! {
     /// A stream to skip first n elements of another stream.
+    ///
+    /// This `struct` is created by the [`skip`] method on [`Stream`]. See its
+    /// documentation for more.
+    ///
+    /// [`skip`]: trait.Stream.html#method.skip
+    /// [`Stream`]: trait.Stream.html
     #[derive(Debug)]
     pub struct Skip<S> {
         #[pin]

src/stream/stream/skip_while.rs

@@ -8,6 +8,12 @@ use crate::task::{Context, Poll};
 
 pin_project! {
     /// A stream to skip elements of another stream based on a predicate.
+    ///
+    /// This `struct` is created by the [`skip_while`] method on [`Stream`]. See its
+    /// documentation for more.
+    ///
+    /// [`skip_while`]: trait.Stream.html#method.skip_while
+    /// [`Stream`]: trait.Stream.html
     #[derive(Debug)]
     pub struct SkipWhile<S, P, T> {
         #[pin]

src/stream/stream/step_by.rs

@@ -7,6 +7,12 @@ use crate::task::{Context, Poll};
 
 pin_project! {
     /// A stream that steps a given amount of elements of another stream.
+    ///
+    /// This `struct` is created by the [`step_by`] method on [`Stream`]. See its
+    /// documentation for more.
+    ///
+    /// [`step_by`]: trait.Stream.html#method.step_by
+    /// [`Stream`]: trait.Stream.html
     #[derive(Debug)]
     pub struct StepBy<S> {
         #[pin]

src/stream/stream/take.rs

@@ -7,6 +7,12 @@ use crate::task::{Context, Poll};
 
 pin_project! {
     /// A stream that yields the first `n` items of another stream.
+    ///
+    /// This `struct` is created by the [`take`] method on [`Stream`]. See its
+    /// documentation for more.
+    ///
+    /// [`take`]: trait.Stream.html#method.take
+    /// [`Stream`]: trait.Stream.html
     #[derive(Clone, Debug)]
     pub struct Take<S> {
         #[pin]

src/stream/stream/take_while.rs

@@ -8,6 +8,12 @@ use crate::task::{Context, Poll};
 
 pin_project! {
     /// A stream that yields elements based on a predicate.
+    ///
+    /// This `struct` is created by the [`take_while`] method on [`Stream`]. See its
+    /// documentation for more.
+    ///
+    /// [`take_while`]: trait.Stream.html#method.take_while
+    /// [`Stream`]: trait.Stream.html
     #[derive(Debug)]
     pub struct TakeWhile<S, P, T> {
         #[pin]

src/stream/stream/zip.rs

@@ -8,6 +8,12 @@ use crate::task::{Context, Poll};
 
 pin_project! {
     /// An iterator that iterates two other iterators simultaneously.
+    ///
+    /// This `struct` is created by the [`zip`] method on [`Stream`]. See its
+    /// documentation for more.
+    ///
+    /// [`zip`]: trait.Stream.html#method.zip
+    /// [`Stream`]: trait.Stream.html
     pub struct Zip<A: Stream, B> {
         item_slot: Option<A::Item>,
         #[pin]