From 5d49c0e55a1ab9757c05df44bee4bf50d9d71f9c Mon Sep 17 00:00:00 2001 From: Alexis Bourget Date: Tue, 18 Aug 2020 19:36:52 +0200 Subject: [PATCH 1/2] Move to intra doc links for std::io --- library/std/src/io/buffered.rs | 50 ++++++++++----------- library/std/src/io/cursor.rs | 14 +++--- library/std/src/io/error.rs | 65 ++++++++++++++------------- library/std/src/io/mod.rs | 81 ++++++++++++++++++---------------- library/std/src/io/stdio.rs | 29 +++--------- library/std/src/io/util.rs | 33 +++++++------- 6 files changed, 126 insertions(+), 146 deletions(-) diff --git a/library/std/src/io/buffered.rs b/library/std/src/io/buffered.rs index b4c91cced43bf..f3aadf29b2f2b 100644 --- a/library/std/src/io/buffered.rs +++ b/library/std/src/io/buffered.rs @@ -21,17 +21,16 @@ use crate::memchr; /// *repeated* read calls to the same file or network socket. It does not /// help when reading very large amounts at once, or reading just one or a few /// times. It also provides no advantage when reading from a source that is -/// already in memory, like a `Vec`. +/// already in memory, like a [`Vec`]``. /// /// When the `BufReader` is dropped, the contents of its buffer will be /// discarded. Creating multiple instances of a `BufReader` on the same /// stream can cause data loss. Reading from the underlying reader after -/// unwrapping the `BufReader` with `BufReader::into_inner` can also cause +/// unwrapping the `BufReader` with [`BufReader::into_inner`] can also cause /// data loss. /// -/// [`Read`]: ../../std/io/trait.Read.html -/// [`TcpStream::read`]: ../../std/net/struct.TcpStream.html#method.read -/// [`TcpStream`]: ../../std/net/struct.TcpStream.html +/// [`TcpStream::read`]: Read::read +/// [`TcpStream`]: crate::net::TcpStream /// /// # Examples /// @@ -155,7 +154,9 @@ impl BufReader { /// Returns a reference to the internally buffered data. /// - /// Unlike `fill_buf`, this will not attempt to fill the buffer if it is empty. + /// Unlike [`fill_buf`], this will not attempt to fill the buffer if it is empty. + /// + /// [`fill_buf`]: BufRead::fill_buf /// /// # Examples /// @@ -338,27 +339,26 @@ where impl Seek for BufReader { /// Seek to an offset, in bytes, in the underlying reader. /// - /// The position used for seeking with `SeekFrom::Current(_)` is the + /// The position used for seeking with [`SeekFrom::Current`]`(_)` is the /// position the underlying reader would be at if the `BufReader` had no /// internal buffer. /// /// Seeking always discards the internal buffer, even if the seek position /// would otherwise fall within it. This guarantees that calling - /// `.into_inner()` immediately after a seek yields the underlying reader + /// [`BufReader::into_inner()`] immediately after a seek yields the underlying reader /// at the same position. /// /// To seek without discarding the internal buffer, use [`BufReader::seek_relative`]. /// /// See [`std::io::Seek`] for more details. /// - /// Note: In the edge case where you're seeking with `SeekFrom::Current(n)` + /// Note: In the edge case where you're seeking with [`SeekFrom::Current`]`(n)` /// where `n` minus the internal buffer length overflows an `i64`, two /// seeks will be performed instead of one. If the second seek returns - /// `Err`, the underlying reader will be left at the same position it would - /// have if you called `seek` with `SeekFrom::Current(0)`. + /// [`Err`], the underlying reader will be left at the same position it would + /// have if you called `seek` with [`SeekFrom::Current`]`(0)`. /// - /// [`BufReader::seek_relative`]: struct.BufReader.html#method.seek_relative - /// [`std::io::Seek`]: trait.Seek.html + /// [`std::io::Seek`]: Seek fn seek(&mut self, pos: SeekFrom) -> io::Result { let result: u64; if let SeekFrom::Current(n) = pos { @@ -397,7 +397,7 @@ impl Seek for BufReader { /// *repeated* write calls to the same file or network socket. It does not /// help when writing very large amounts at once, or writing just one or a few /// times. It also provides no advantage when writing to a destination that is -/// in memory, like a `Vec`. +/// in memory, like a [`Vec`]`. /// /// It is critical to call [`flush`] before `BufWriter` is dropped. Though /// dropping will attempt to flush the contents of the buffer, any errors @@ -441,10 +441,9 @@ impl Seek for BufReader { /// together by the buffer and will all be written out in one system call when /// the `stream` is flushed. /// -/// [`Write`]: ../../std/io/trait.Write.html -/// [`TcpStream::write`]: ../../std/net/struct.TcpStream.html#method.write -/// [`TcpStream`]: ../../std/net/struct.TcpStream.html -/// [`flush`]: #method.flush +/// [`TcpStream::write`]: Write::write +/// [`TcpStream`]: crate::net::TcpStream +/// [`flush`]: Write::flush #[stable(feature = "rust1", since = "1.0.0")] pub struct BufWriter { inner: Option, @@ -455,7 +454,7 @@ pub struct BufWriter { panicked: bool, } -/// An error returned by `into_inner` which combines an error that +/// An error returned by [`BufWriter::into_inner`] which combines an error that /// happened while writing out the buffer, and the buffered writer object /// which may be used to recover from the condition. /// @@ -629,7 +628,7 @@ impl BufWriter { /// /// # Errors /// - /// An `Err` will be returned if an error occurs while flushing the buffer. + /// An [`Err`] will be returned if an error occurs while flushing the buffer. /// /// # Examples /// @@ -725,7 +724,8 @@ impl Drop for BufWriter { } impl IntoInnerError { - /// Returns the error which caused the call to `into_inner()` to fail. + /// Returns the error which caused the call to [`BufWriter::into_inner()`] + /// to fail. /// /// This error was returned when attempting to write the internal buffer. /// @@ -819,17 +819,15 @@ impl fmt::Display for IntoInnerError { /// Wraps a writer and buffers output to it, flushing whenever a newline /// (`0x0a`, `'\n'`) is detected. /// -/// The [`BufWriter`][bufwriter] struct wraps a writer and buffers its output. +/// The [`BufWriter`] struct wraps a writer and buffers its output. /// But it only does this batched write when it goes out of scope, or when the /// internal buffer is full. Sometimes, you'd prefer to write each line as it's /// completed, rather than the entire buffer at once. Enter `LineWriter`. It /// does exactly that. /// -/// Like [`BufWriter`][bufwriter], a `LineWriter`’s buffer will also be flushed when the +/// Like [`BufWriter`], a `LineWriter`’s buffer will also be flushed when the /// `LineWriter` goes out of scope or when its internal buffer is full. /// -/// [bufwriter]: struct.BufWriter.html -/// /// If there's still a partial line in the buffer when the `LineWriter` is /// dropped, it will flush those contents. /// @@ -979,7 +977,7 @@ impl LineWriter { /// /// # Errors /// - /// An `Err` will be returned if an error occurs while flushing the buffer. + /// An [`Err`] will be returned if an error occurs while flushing the buffer. /// /// # Examples /// diff --git a/library/std/src/io/cursor.rs b/library/std/src/io/cursor.rs index f4db5f8145060..58343f66f3ffd 100644 --- a/library/std/src/io/cursor.rs +++ b/library/std/src/io/cursor.rs @@ -9,7 +9,7 @@ use core::convert::TryInto; /// [`Seek`] implementation. /// /// `Cursor`s are used with in-memory buffers, anything implementing -/// `AsRef<[u8]>`, to allow them to implement [`Read`] and/or [`Write`], +/// [`AsRef`]`<[u8]>`, to allow them to implement [`Read`] and/or [`Write`], /// allowing these buffers to be used anywhere you might use a reader or writer /// that does actual I/O. /// @@ -23,12 +23,8 @@ use core::convert::TryInto; /// code, but use an in-memory buffer in our tests. We can do this with /// `Cursor`: /// -/// [`Seek`]: trait.Seek.html -/// [`Read`]: ../../std/io/trait.Read.html -/// [`Write`]: ../../std/io/trait.Write.html -/// [`Vec`]: ../../std/vec/struct.Vec.html -/// [bytes]: ../../std/primitive.slice.html -/// [`File`]: ../fs/struct.File.html +/// [bytes]: crate::slice +/// [`File`]: crate::fs::File /// /// ```no_run /// use std::io::prelude::*; @@ -81,8 +77,8 @@ pub struct Cursor { impl Cursor { /// Creates a new cursor wrapping the provided underlying in-memory buffer. /// - /// Cursor initial position is `0` even if underlying buffer (e.g., `Vec`) - /// is not empty. So writing to cursor starts with overwriting `Vec` + /// Cursor initial position is `0` even if underlying buffer (e.g., [`Vec`]) + /// is not empty. So writing to cursor starts with overwriting [`Vec`] /// content, not with appending to it. /// /// # Examples diff --git a/library/std/src/io/error.rs b/library/std/src/io/error.rs index f7248e7547e27..e6eda2caf758f 100644 --- a/library/std/src/io/error.rs +++ b/library/std/src/io/error.rs @@ -4,8 +4,7 @@ use crate::fmt; use crate::result; use crate::sys; -/// A specialized [`Result`](../result/enum.Result.html) type for I/O -/// operations. +/// A specialized [`Result`] type for I/O operations. /// /// This type is broadly used across [`std::io`] for any operation which may /// produce an error. @@ -16,12 +15,13 @@ use crate::sys; /// While usual Rust style is to import types directly, aliases of [`Result`] /// often are not, to make it easier to distinguish between them. [`Result`] is /// generally assumed to be [`std::result::Result`][`Result`], and so users of this alias -/// will generally use `io::Result` instead of shadowing the prelude's import +/// will generally use `io::Result` instead of shadowing the [prelude]'s import /// of [`std::result::Result`][`Result`]. /// -/// [`std::io`]: ../io/index.html -/// [`io::Error`]: ../io/struct.Error.html -/// [`Result`]: ../result/enum.Result.html +/// [`std::io`]: crate::io +/// [`io::Error`]: Error +/// [`Result`]: crate::result::Result +/// [prelude]: crate::prelude /// /// # Examples /// @@ -48,10 +48,9 @@ pub type Result = result::Result; /// `Error` can be created with crafted error messages and a particular value of /// [`ErrorKind`]. /// -/// [`Read`]: ../io/trait.Read.html -/// [`Write`]: ../io/trait.Write.html -/// [`Seek`]: ../io/trait.Seek.html -/// [`ErrorKind`]: enum.ErrorKind.html +/// [`Read`]: crate::io::Read +/// [`Write`]: crate::io::Write +/// [`Seek`]: crate::io::Seek #[stable(feature = "rust1", since = "1.0.0")] pub struct Error { repr: Repr, @@ -83,7 +82,7 @@ struct Custom { /// /// It is used with the [`io::Error`] type. /// -/// [`io::Error`]: struct.Error.html +/// [`io::Error`]: Error #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] #[stable(feature = "rust1", since = "1.0.0")] #[allow(deprecated)] @@ -137,7 +136,7 @@ pub enum ErrorKind { /// For example, a function that reads a file into a string will error with /// `InvalidData` if the file's contents are not valid UTF-8. /// - /// [`InvalidInput`]: #variant.InvalidInput + /// [`InvalidInput`]: ErrorKind::InvalidInput #[stable(feature = "io_invalid_data", since = "1.2.0")] InvalidData, /// The I/O operation's timeout expired, causing it to be canceled. @@ -150,8 +149,8 @@ pub enum ErrorKind { /// particular number of bytes but only a smaller number of bytes could be /// written. /// - /// [`write`]: ../../std/io/trait.Write.html#tymethod.write - /// [`Ok(0)`]: ../../std/io/type.Result.html + /// [`write`]: crate::io::Write::write + /// [`Ok(0)`]: Ok #[stable(feature = "rust1", since = "1.0.0")] WriteZero, /// This operation was interrupted. @@ -220,9 +219,6 @@ impl From for Error { /// let error = Error::from(not_found); /// assert_eq!("entity not found", format!("{}", error)); /// ``` - /// - /// [`ErrorKind`]: ../../std/io/enum.ErrorKind.html - /// [`Error`]: ../../std/io/struct.Error.html #[inline] fn from(kind: ErrorKind) -> Error { Error { repr: Repr::Simple(kind) } @@ -235,7 +231,7 @@ impl Error { /// /// This function is used to generically create I/O errors which do not /// originate from the OS itself. The `error` argument is an arbitrary - /// payload which will be contained in this `Error`. + /// payload which will be contained in this [`Error`]. /// /// # Examples /// @@ -264,7 +260,7 @@ impl Error { /// /// This function reads the value of `errno` for the target platform (e.g. /// `GetLastError` on Windows) and will return a corresponding instance of - /// `Error` for the error code. + /// [`Error`] for the error code. /// /// # Examples /// @@ -278,7 +274,7 @@ impl Error { Error::from_raw_os_error(sys::os::errno() as i32) } - /// Creates a new instance of an `Error` from a particular OS error code. + /// Creates a new instance of an [`Error`] from a particular OS error code. /// /// # Examples /// @@ -310,9 +306,12 @@ impl Error { /// Returns the OS error that this error represents (if any). /// - /// If this `Error` was constructed via `last_os_error` or - /// `from_raw_os_error`, then this function will return `Some`, otherwise - /// it will return `None`. + /// If this [`Error`] was constructed via [`last_os_error`] or + /// [`from_raw_os_error`], then this function will return [`Some`], otherwise + /// it will return [`None`]. + /// + /// [`last_os_error`]: Error::last_os_error + /// [`from_raw_os_error`]: Error::from_raw_os_error /// /// # Examples /// @@ -345,8 +344,10 @@ impl Error { /// Returns a reference to the inner error wrapped by this error (if any). /// - /// If this `Error` was constructed via `new` then this function will - /// return `Some`, otherwise it will return `None`. + /// If this [`Error`] was constructed via [`new`] then this function will + /// return [`Some`], otherwise it will return [`None`]. + /// + /// [`new`]: Error::new /// /// # Examples /// @@ -380,8 +381,10 @@ impl Error { /// Returns a mutable reference to the inner error wrapped by this error /// (if any). /// - /// If this `Error` was constructed via `new` then this function will - /// return `Some`, otherwise it will return `None`. + /// If this [`Error`] was constructed via [`new`] then this function will + /// return [`Some`], otherwise it will return [`None`]. + /// + /// [`new`]: Error::new /// /// # Examples /// @@ -448,8 +451,10 @@ impl Error { /// Consumes the `Error`, returning its inner error (if any). /// - /// If this `Error` was constructed via `new` then this function will - /// return `Some`, otherwise it will return `None`. + /// If this [`Error`] was constructed via [`new`] then this function will + /// return [`Some`], otherwise it will return [`None`]. + /// + /// [`new`]: Error::new /// /// # Examples /// @@ -480,7 +485,7 @@ impl Error { } } - /// Returns the corresponding `ErrorKind` for this error. + /// Returns the corresponding [`ErrorKind`] for this error. /// /// # Examples /// diff --git a/library/std/src/io/mod.rs b/library/std/src/io/mod.rs index e90ee5c285f2f..f1ee3c6986062 100644 --- a/library/std/src/io/mod.rs +++ b/library/std/src/io/mod.rs @@ -240,9 +240,9 @@ //! //! [`File`]: crate::fs::File //! [`TcpStream`]: crate::net::TcpStream -//! [`Vec`]: crate::vec::Vec +//! [`Vec`]: Vec //! [`io::stdout`]: stdout -//! [`io::Result`]: crate::io::Result +//! [`io::Result`]: self::Result //! [`?` operator]: ../../book/appendix-02-operators.html //! [`Result`]: crate::result::Result //! [`.unwrap()`]: crate::result::Result::unwrap @@ -479,11 +479,11 @@ where /// } /// ``` /// -/// [`read()`]: Read::read +/// [`read()`]: Self::read /// [`&str`]: str /// [`std::io`]: self /// [`File`]: crate::fs::File -/// [slice]: ../../std/primitive.slice.html +/// [slice]: crate::slice #[stable(feature = "rust1", since = "1.0.0")] #[doc(spotlight)] pub trait Read { @@ -633,7 +633,7 @@ pub trait Read { /// /// [`File`]s implement `Read`: /// - /// [`read()`]: Read::read + /// [`read()`]: Self::read /// [`Ok(0)`]: Ok /// [`File`]: crate::fs::File /// @@ -671,15 +671,15 @@ pub trait Read { /// If the data in this stream is *not* valid UTF-8 then an error is /// returned and `buf` is unchanged. /// - /// See [`read_to_end`][readtoend] for other error semantics. + /// See [`read_to_end`] for other error semantics. /// - /// [readtoend]: Self::read_to_end + /// [`read_to_end`]: Self::read_to_end /// /// # Examples /// - /// [`File`][file]s implement `Read`: + /// [`File`]s implement `Read`: /// - /// [file]: crate::fs::File + /// [`File`]: crate::fs::File /// /// ```no_run /// use std::io; @@ -746,7 +746,7 @@ pub trait Read { /// /// [`File`]s implement `Read`: /// - /// [`read`]: Read::read + /// [`read`]: Self::read /// [`File`]: crate::fs::File /// /// ```no_run @@ -790,9 +790,9 @@ pub trait Read { /// /// # Examples /// - /// [`File`][file]s implement `Read`: + /// [`File`]s implement `Read`: /// - /// [file]: crate::fs::File + /// [`File`]: crate::fs::File /// /// ```no_run /// use std::io; @@ -834,10 +834,9 @@ pub trait Read { /// /// # Examples /// - /// [`File`][file]s implement `Read`: + /// [`File`]s implement `Read`: /// - /// [file]: crate::fs::File - /// [`Iterator`]: crate::iter::Iterator + /// [`File`]: crate::fs::File /// [`Result`]: crate::result::Result /// [`io::Error`]: self::Error /// @@ -871,9 +870,9 @@ pub trait Read { /// /// # Examples /// - /// [`File`][file]s implement `Read`: + /// [`File`]s implement `Read`: /// - /// [file]: crate::fs::File + /// [`File`]: crate::fs::File /// /// ```no_run /// use std::io; @@ -1283,30 +1282,36 @@ pub trait Write { /// Ok(()) /// } /// ``` + /// + /// [`Ok(n)`]: Ok #[stable(feature = "rust1", since = "1.0.0")] fn write(&mut self, buf: &[u8]) -> Result; - /// Like `write`, except that it writes from a slice of buffers. + /// Like [`write`], except that it writes from a slice of buffers. /// /// Data is copied from each buffer in order, with the final buffer /// read from possibly being only partially consumed. This method must - /// behave as a call to `write` with the buffers concatenated would. + /// behave as a call to [`write`] with the buffers concatenated would. /// - /// The default implementation calls `write` with either the first nonempty + /// The default implementation calls [`write`] with either the first nonempty /// buffer provided, or an empty one if none exists. + /// + /// [`write`]: Self::write #[stable(feature = "iovec", since = "1.36.0")] fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result { default_write_vectored(|b| self.write(b), bufs) } - /// Determines if this `Write`er has an efficient `write_vectored` + /// Determines if this `Write`er has an efficient [`write_vectored`] /// implementation. /// - /// If a `Write`er does not override the default `write_vectored` + /// If a `Write`er does not override the default [`write_vectored`] /// implementation, code using it may want to avoid the method all together /// and coalesce writes into a single buffer for higher performance. /// /// The default implementation returns `false`. + /// + /// [`write_vectored`]: Self::write_vectored #[unstable(feature = "can_vector", issue = "69941")] fn is_write_vectored(&self) -> bool { false @@ -1399,16 +1404,15 @@ pub trait Write { /// /// # Notes /// - /// - /// Unlike `io::Write::write_vectored`, this takes a *mutable* reference to - /// a slice of `IoSlice`s, not an immutable one. That's because we need to + /// Unlike [`write_vectored`], this takes a *mutable* reference to + /// a slice of [`IoSlice`]s, not an immutable one. That's because we need to /// modify the slice to keep track of the bytes already written. /// /// Once this function returns, the contents of `bufs` are unspecified, as - /// this depends on how many calls to `write_vectored` were necessary. It is + /// this depends on how many calls to [`write_vectored`] were necessary. It is /// best to understand this function as taking ownership of `bufs` and to /// not use `bufs` afterwards. The underlying buffers, to which the - /// `IoSlice`s point (but not the `IoSlice`s themselves), are unchanged and + /// [`IoSlice`]s point (but not the [`IoSlice`]s themselves), are unchanged and /// can be reused. /// /// # Examples @@ -1458,12 +1462,12 @@ pub trait Write { /// explicitly be called. The [`write!()`] macro should be favored to /// invoke this method instead. /// - /// This function internally uses the [`write_all`][writeall] method on + /// This function internally uses the [`write_all`] method on /// this trait and hence will continuously write data so long as no errors /// are received. This also means that partial writes are not indicated in /// this signature. /// - /// [writeall]: Self::write_all + /// [`write_all`]: Self::write_all /// /// # Errors /// @@ -1558,9 +1562,9 @@ pub trait Write { /// /// # Examples /// -/// [`File`][file]s implement `Seek`: +/// [`File`]s implement `Seek`: /// -/// [file]: crate::fs::File +/// [`File`]: crate::fs::File /// /// ```no_run /// use std::io; @@ -1610,7 +1614,6 @@ pub trait Seek { /// data is appended to a file). So calling this method multiple times does /// not necessarily return the same length each time. /// - /// /// # Example /// /// ```no_run @@ -1646,7 +1649,6 @@ pub trait Seek { /// /// This is equivalent to `self.seek(SeekFrom::Current(0))`. /// - /// /// # Example /// /// ```no_run @@ -1775,7 +1777,6 @@ fn read_until(r: &mut R, delim: u8, buf: &mut Vec) -> R /// Ok(()) /// } /// ``` -/// #[stable(feature = "rust1", since = "1.0.0")] pub trait BufRead: Read { /// Returns the contents of the internal buffer, filling it with more data @@ -1901,22 +1902,24 @@ pub trait BufRead: Read { read_until(self, byte, buf) } - /// Read all bytes until a newline (the 0xA byte) is reached, and append + /// Read all bytes until a newline (the `0xA` byte) is reached, and append /// them to the provided buffer. /// /// This function will read bytes from the underlying stream until the - /// newline delimiter (the 0xA byte) or EOF is found. Once found, all bytes + /// newline delimiter (the `0xA` byte) or EOF is found. Once found, all bytes /// up to, and including, the delimiter (if found) will be appended to /// `buf`. /// /// If successful, this function will return the total number of bytes read. /// - /// If this function returns `Ok(0)`, the stream has reached EOF. + /// If this function returns [`Ok(0)`], the stream has reached EOF. /// /// This function is blocking and should be used carefully: it is possible for /// an attacker to continuously send bytes without ever sending a newline /// or EOF. /// + /// [`Ok(0)`]: Ok + /// /// # Errors /// /// This function has the same error semantics as [`read_until`] and will @@ -1976,7 +1979,7 @@ pub trait BufRead: Read { /// also yielded an error. /// /// [`io::Result`]: self::Result - /// [`Vec`]: crate::vec::Vec + /// [`Vec`]: Vec /// [`read_until`]: Self::read_until /// /// # Examples @@ -2008,7 +2011,7 @@ pub trait BufRead: Read { /// /// The iterator returned from this function will yield instances of /// [`io::Result`]`<`[`String`]`>`. Each string returned will *not* have a newline - /// byte (the 0xA byte) or CRLF (0xD, 0xA bytes) at the end. + /// byte (the `0xA` byte) or CRLF (0xD, 0xA bytes) at the end. /// /// [`io::Result`]: self::Result /// diff --git a/library/std/src/io/stdio.rs b/library/std/src/io/stdio.rs index 156f555be02d8..286eb92915e49 100644 --- a/library/std/src/io/stdio.rs +++ b/library/std/src/io/stdio.rs @@ -252,8 +252,7 @@ fn handle_ebadf(r: io::Result, default: T) -> io::Result { /// /// Created by the [`io::stdin`] method. /// -/// [`io::stdin`]: fn.stdin.html -/// [`BufRead`]: trait.BufRead.html +/// [`io::stdin`]: stdin /// /// ### Note: Windows Portability Consideration /// @@ -283,10 +282,6 @@ pub struct Stdin { /// This handle implements both the [`Read`] and [`BufRead`] traits, and /// is constructed via the [`Stdin::lock`] method. /// -/// [`Read`]: trait.Read.html -/// [`BufRead`]: trait.BufRead.html -/// [`Stdin::lock`]: struct.Stdin.html#method.lock -/// /// ### Note: Windows Portability Consideration /// /// When operating in a console, the Windows implementation of this stream does not support @@ -319,8 +314,6 @@ pub struct StdinLock<'a> { /// is synchronized via a mutex. If you need more explicit control over /// locking, see the [`Stdin::lock`] method. /// -/// [`Stdin::lock`]: struct.Stdin.html#method.lock -/// /// ### 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 read bytes that are not valid UTF-8 will return @@ -380,9 +373,6 @@ impl Stdin { /// returned guard also implements the [`Read`] and [`BufRead`] traits for /// accessing the underlying data. /// - /// [`Read`]: trait.Read.html - /// [`BufRead`]: trait.BufRead.html - /// /// # Examples /// /// ```no_run @@ -407,8 +397,6 @@ impl Stdin { /// For detailed semantics of this method, see the documentation on /// [`BufRead::read_line`]. /// - /// [`BufRead::read_line`]: trait.BufRead.html#method.read_line - /// /// # Examples /// /// ```no_run @@ -542,8 +530,8 @@ impl fmt::Debug for StdinLock<'_> { /// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return /// an error. /// -/// [`lock`]: #method.lock -/// [`io::stdout`]: fn.stdout.html +/// [`lock`]: Stdout::lock +/// [`io::stdout`]: stdout #[stable(feature = "rust1", since = "1.0.0")] pub struct Stdout { // FIXME: this should be LineWriter or BufWriter depending on the state of @@ -561,9 +549,6 @@ pub struct 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. -/// -/// [`Write`]: trait.Write.html -/// [`Stdout::lock`]: struct.Stdout.html#method.lock #[stable(feature = "rust1", since = "1.0.0")] pub struct StdoutLock<'a> { inner: ReentrantMutexGuard<'a, RefCell>>>, @@ -575,8 +560,6 @@ pub struct StdoutLock<'a> { /// is synchronized via a mutex. If you need more explicit control over /// locking, see the [`Stdout::lock`] method. /// -/// [`Stdout::lock`]: struct.Stdout.html#method.lock -/// /// ### 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 @@ -724,7 +707,7 @@ impl fmt::Debug for StdoutLock<'_> { /// /// For more information, see the [`io::stderr`] method. /// -/// [`io::stderr`]: fn.stderr.html +/// [`io::stderr`]: stderr /// /// ### Note: Windows Portability Consideration /// When operating in a console, the Windows implementation of this stream does not support @@ -740,8 +723,6 @@ pub struct Stderr { /// This handle implements the `Write` trait and is constructed via /// the [`Stderr::lock`] method. /// -/// [`Stderr::lock`]: struct.Stderr.html#method.lock -/// /// ### 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 @@ -819,7 +800,7 @@ impl Stderr { /// guard. /// /// The lock is released when the returned lock goes out of scope. The - /// returned guard also implements the `Write` trait for writing data. + /// returned guard also implements the [`Write`] trait for writing data. /// /// # Examples /// diff --git a/library/std/src/io/util.rs b/library/std/src/io/util.rs index b9d5dc27db006..a093b745b0c13 100644 --- a/library/std/src/io/util.rs +++ b/library/std/src/io/util.rs @@ -16,14 +16,17 @@ use crate::mem::MaybeUninit; /// If you’re wanting to copy the contents of one file to another and you’re /// working with filesystem paths, see the [`fs::copy`] function. /// -/// [`fs::copy`]: ../fs/fn.copy.html +/// [`fs::copy`]: crate::fs::copy /// /// # Errors /// -/// This function will return an error immediately if any call to `read` or -/// `write` returns an error. All instances of `ErrorKind::Interrupted` are +/// This function will return an error immediately if any call to [`read`] or +/// [`write`] returns an error. All instances of [`ErrorKind::Interrupted`] are /// handled by this function and the underlying operation is retried. /// +/// [`read`]: Read::read +/// [`write`]: Write::write +/// /// # Examples /// /// ``` @@ -70,10 +73,8 @@ where /// A reader which is always at EOF. /// -/// This struct is generally created by calling [`empty`]. Please see -/// the documentation of [`empty()`][`empty`] for more details. -/// -/// [`empty`]: fn.empty.html +/// This struct is generally created by calling [`empty()`]. Please see +/// the documentation of [`empty()`] for more details. #[stable(feature = "rust1", since = "1.0.0")] pub struct Empty { _priv: (), @@ -83,8 +84,6 @@ pub struct Empty { /// /// All reads from the returned reader will return [`Ok`]`(0)`. /// -/// [`Ok`]: ../result/enum.Result.html#variant.Ok -/// /// # Examples /// /// A slightly sad example of not reading anything into a buffer: @@ -132,10 +131,8 @@ impl fmt::Debug for Empty { /// A reader which yields one byte over and over and over and over and over and... /// -/// This struct is generally created by calling [`repeat`][repeat]. Please -/// see the documentation of `repeat()` for more details. -/// -/// [repeat]: fn.repeat.html +/// This struct is generally created by calling [`repeat()`]. Please +/// see the documentation of [`repeat()`] for more details. #[stable(feature = "rust1", since = "1.0.0")] pub struct Repeat { byte: u8, @@ -199,10 +196,8 @@ impl fmt::Debug for Repeat { /// A writer which will move data into the void. /// -/// This struct is generally created by calling [`sink`][sink]. Please -/// see the documentation of `sink()` for more details. -/// -/// [sink]: fn.sink.html +/// This struct is generally created by calling [`sink`]. Please +/// see the documentation of [`sink()`] for more details. #[stable(feature = "rust1", since = "1.0.0")] pub struct Sink { _priv: (), @@ -210,9 +205,11 @@ pub struct Sink { /// Creates an instance of a writer which will successfully consume all data. /// -/// All calls to `write` on the returned instance will return `Ok(buf.len())` +/// All calls to [`write`] on the returned instance will return `Ok(buf.len())` /// and the contents of the buffer will not be inspected. /// +/// [`write`]: Write::write +/// /// # Examples /// /// ```rust From dad8e11e9fcbd76c0a2dc47211dcd654effed010 Mon Sep 17 00:00:00 2001 From: Alexis Bourget Date: Wed, 19 Aug 2020 16:26:17 +0200 Subject: [PATCH 2/2] Fix nits in intra-doc links for std io --- library/std/src/io/mod.rs | 44 +++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/library/std/src/io/mod.rs b/library/std/src/io/mod.rs index f1ee3c6986062..3245629483828 100644 --- a/library/std/src/io/mod.rs +++ b/library/std/src/io/mod.rs @@ -479,11 +479,11 @@ where /// } /// ``` /// -/// [`read()`]: Self::read +/// [`read()`]: Read::read /// [`&str`]: str /// [`std::io`]: self /// [`File`]: crate::fs::File -/// [slice]: crate::slice +/// [slice]: ../../std/primitive.slice.html #[stable(feature = "rust1", since = "1.0.0")] #[doc(spotlight)] pub trait Read { @@ -633,7 +633,7 @@ pub trait Read { /// /// [`File`]s implement `Read`: /// - /// [`read()`]: Self::read + /// [`read()`]: Read::read /// [`Ok(0)`]: Ok /// [`File`]: crate::fs::File /// @@ -673,7 +673,7 @@ pub trait Read { /// /// See [`read_to_end`] for other error semantics. /// - /// [`read_to_end`]: Self::read_to_end + /// [`read_to_end`]: Read::read_to_end /// /// # Examples /// @@ -746,7 +746,7 @@ pub trait Read { /// /// [`File`]s implement `Read`: /// - /// [`read`]: Self::read + /// [`read`]: Read::read /// [`File`]: crate::fs::File /// /// ```no_run @@ -1209,8 +1209,8 @@ impl Initializer { /// throughout [`std::io`] take and provide types which implement the `Write` /// trait. /// -/// [`write`]: Self::write -/// [`flush`]: Self::flush +/// [`write`]: Write::write +/// [`flush`]: Write::flush /// [`std::io`]: self /// /// # Examples @@ -1236,7 +1236,7 @@ impl Initializer { /// The trait also provides convenience methods like [`write_all`], which calls /// `write` in a loop until its entire input has been written. /// -/// [`write_all`]: Self::write_all +/// [`write_all`]: Write::write_all #[stable(feature = "rust1", since = "1.0.0")] #[doc(spotlight)] pub trait Write { @@ -1296,7 +1296,7 @@ pub trait Write { /// The default implementation calls [`write`] with either the first nonempty /// buffer provided, or an empty one if none exists. /// - /// [`write`]: Self::write + /// [`write`]: Write::write #[stable(feature = "iovec", since = "1.36.0")] fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result { default_write_vectored(|b| self.write(b), bufs) @@ -1311,7 +1311,7 @@ pub trait Write { /// /// The default implementation returns `false`. /// - /// [`write_vectored`]: Self::write_vectored + /// [`write_vectored`]: Write::write_vectored #[unstable(feature = "can_vector", issue = "69941")] fn is_write_vectored(&self) -> bool { false @@ -1359,7 +1359,7 @@ pub trait Write { /// This function will return the first error of /// non-[`ErrorKind::Interrupted`] kind that [`write`] returns. /// - /// [`write`]: Self::write + /// [`write`]: Write::write /// /// # Examples /// @@ -1400,8 +1400,6 @@ pub trait Write { /// /// If the buffer contains no data, this will never call [`write_vectored`]. /// - /// [`write_vectored`]: Self::write_vectored - /// /// # Notes /// /// Unlike [`write_vectored`], this takes a *mutable* reference to @@ -1415,6 +1413,8 @@ pub trait Write { /// [`IoSlice`]s point (but not the [`IoSlice`]s themselves), are unchanged and /// can be reused. /// + /// [`write_vectored`]: Write::write_vectored + /// /// # Examples /// /// ``` @@ -1467,7 +1467,7 @@ pub trait Write { /// are received. This also means that partial writes are not indicated in /// this signature. /// - /// [`write_all`]: Self::write_all + /// [`write_all`]: Write::write_all /// /// # Errors /// @@ -1758,8 +1758,8 @@ fn read_until(r: &mut R, delim: u8, buf: &mut Vec) -> R /// [`BufReader`] to the rescue! /// /// [`File`]: crate::fs::File -/// [`read_line`]: Self::read_line -/// [`lines`]: Self::lines +/// [`read_line`]: BufRead::read_line +/// [`lines`]: BufRead::lines /// /// ```no_run /// use std::io::{self, BufReader}; @@ -1789,7 +1789,7 @@ pub trait BufRead: Read { /// be called with the number of bytes that are consumed from this buffer to /// ensure that the bytes are never returned twice. /// - /// [`consume`]: Self::consume + /// [`consume`]: BufRead::consume /// /// An empty buffer returned indicates that the stream has reached EOF. /// @@ -1839,7 +1839,7 @@ pub trait BufRead: Read { /// Since `consume()` is meant to be used with [`fill_buf`], /// that method's example includes an example of `consume()`. /// - /// [`fill_buf`]: Self::fill_buf + /// [`fill_buf`]: BufRead::fill_buf #[stable(feature = "rust1", since = "1.0.0")] fn consume(&mut self, amt: usize); @@ -1863,7 +1863,7 @@ pub trait BufRead: Read { /// If an I/O error is encountered then all bytes read so far will be /// present in `buf` and its length will have been adjusted appropriately. /// - /// [`fill_buf`]: Self::fill_buf + /// [`fill_buf`]: BufRead::fill_buf /// /// # Examples /// @@ -1927,7 +1927,7 @@ pub trait BufRead: Read { /// error is encountered then `buf` may contain some bytes already read in /// the event that all data read so far was valid UTF-8. /// - /// [`read_until`]: Self::read_until + /// [`read_until`]: BufRead::read_until /// /// # Examples /// @@ -1980,7 +1980,7 @@ pub trait BufRead: Read { /// /// [`io::Result`]: self::Result /// [`Vec`]: Vec - /// [`read_until`]: Self::read_until + /// [`read_until`]: BufRead::read_until /// /// # Examples /// @@ -2011,7 +2011,7 @@ pub trait BufRead: Read { /// /// The iterator returned from this function will yield instances of /// [`io::Result`]`<`[`String`]`>`. Each string returned will *not* have a newline - /// byte (the `0xA` byte) or CRLF (0xD, 0xA bytes) at the end. + /// byte (the `0xA` byte) or `CRLF` (`0xD`, `0xA` bytes) at the end. /// /// [`io::Result`]: self::Result ///