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

backreference links for structs

Author: yoshuawuyts

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.
+///
+/// ### Note: Windows Portability Consideration
 ///
-/// This type is an async version of [`std::io::Stderr`].
+/// 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.
+///
+/// ### Note: Windows Portability Consideration
 ///
-/// This type is an async version of [`std::io::Stdin`].
+/// 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.
+///
+/// ### Note: Windows Portability Consideration
 ///
-/// This type is an async version of [`std::io::Stdout`].
+/// 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)]