@@ -401,28 +401,29 @@ fn read_to_end<R: Read + ?Sized>(r: &mut R, buf: &mut Vec<u8>) -> Result<usize>
401401///
402402/// Implementors of the `Read` trait are called 'readers'.
403403///
404- /// Readers are defined by one required method, `read()`. Each call to `read`
404+ /// Readers are defined by one required method, [ `read()`] . Each call to [ `read()`]
405405/// will attempt to pull bytes from this source into a provided buffer. A
406- /// number of other methods are implemented in terms of `read()`, giving
406+ /// number of other methods are implemented in terms of [ `read()`] , giving
407407/// implementors a number of ways to read bytes while only needing to implement
408408/// a single method.
409409///
410410/// Readers are intended to be composable with one another. Many implementors
411- /// throughout `std::io` take and provide types which implement the `Read`
411+ /// throughout [ `std::io`] take and provide types which implement the `Read`
412412/// trait.
413413///
414- /// Please note that each call to `read` may involve a system call, and
415- /// therefore, using something that implements [`BufRead`][bufread], such as
416- /// [`BufReader`][bufreader], will be more efficient.
417- ///
418- /// [bufread]: trait.BufRead.html
419- /// [bufreader]: struct.BufReader.html
414+ /// Please note that each call to [`read()`] may involve a system call, and
415+ /// therefore, using something that implements [`BufRead`], such as
416+ /// [`BufReader`], will be more efficient.
420417///
421418/// # Examples
422419///
423- /// [`File`][file] s implement `Read`:
420+ /// [`File`]s implement `Read`:
424421///
425- /// [file]: ../fs/struct.File.html
422+ /// [`read()`]: trait.Read.html#tymethod.read
423+ /// [`std::io`]: ../../std/io/index.html
424+ /// [`File`]: ../fs/struct.File.html
425+ /// [`BufRead`]: trait.BufRead.html
426+ /// [`BufReader`]: struct.BufReader.html
426427///
427428/// ```
428429/// use std::io;
@@ -455,9 +456,9 @@ pub trait Read {
455456 ///
456457 /// This function does not provide any guarantees about whether it blocks
457458 /// waiting for data, but if an object needs to block for a read but cannot
458- /// it will typically signal this via an `Err` return value.
459+ /// it will typically signal this via an [ `Err`] return value.
459460 ///
460- /// If the return value of this method is `Ok(n)`, then it must be
461+ /// If the return value of this method is [ `Ok(n)`] , then it must be
461462 /// guaranteed that `0 <= n <= buf.len()`. A nonzero `n` value indicates
462463 /// that the buffer `buf` has been filled in with `n` bytes of data from this
463464 /// source. If `n` is `0`, then it can indicate one of two scenarios:
@@ -478,14 +479,17 @@ pub trait Read {
478479 /// variant will be returned. If an error is returned then it must be
479480 /// guaranteed that no bytes were read.
480481 ///
481- /// An error of the `ErrorKind::Interrupted` kind is non-fatal and the read
482+ /// An error of the [ `ErrorKind::Interrupted`] kind is non-fatal and the read
482483 /// operation should be retried if there is nothing else to do.
483484 ///
484485 /// # Examples
485486 ///
486- /// [`File`][file] s implement `Read`:
487+ /// [`File`]s implement `Read`:
487488 ///
488- /// [file]: ../fs/struct.File.html
489+ /// [`Err`]: ../../std/result/enum.Result.html#variant.Err
490+ /// [`Ok(n)`]: ../../std/result/enum.Result.html#variant.Ok
491+ /// [`ErrorKind::Interrupted`]: ../../std/io/enum.ErrorKind.html#variant.Interrupted
492+ /// [`File`]: ../fs/struct.File.html
489493 ///
490494 /// ```
491495 /// use std::io;
@@ -511,8 +515,8 @@ pub trait Read {
511515 /// buffers.
512516 ///
513517 /// If a `Read`er guarantees that it can work properly with uninitialized
514- /// memory, it should call `Initializer::nop()`. See the documentation for
515- /// `Initializer` for details.
518+ /// memory, it should call [ `Initializer::nop()`] . See the documentation for
519+ /// [ `Initializer`] for details.
516520 ///
517521 /// The behavior of this method must be independent of the state of the
518522 /// `Read`er - the method only takes `&self` so that it can be used through
@@ -523,6 +527,9 @@ pub trait Read {
523527 /// This method is unsafe because a `Read`er could otherwise return a
524528 /// non-zeroing `Initializer` from another `Read` type without an `unsafe`
525529 /// block.
530+ ///
531+ /// [`Initializer::nop()`]: ../../std/io/struct.Initializer.html#method.nop
532+ /// [`Initializer`]: ../../std/io/struct.Initializer.html
526533 #[ unstable( feature = "read_initializer" , issue = "42788" ) ]
527534 #[ inline]
528535 unsafe fn initializer ( & self ) -> Initializer {
@@ -532,16 +539,16 @@ pub trait Read {
532539 /// Read all bytes until EOF in this source, placing them into `buf`.
533540 ///
534541 /// All bytes read from this source will be appended to the specified buffer
535- /// `buf`. This function will continuously call `read` to append more data to
536- /// `buf` until `read` returns either `Ok(0)` or an error of
537- /// non-`ErrorKind::Interrupted` kind.
542+ /// `buf`. This function will continuously call [ `read()`] to append more data to
543+ /// `buf` until [ `read()`] returns either [ `Ok(0)`] or an error of
544+ /// non-[ `ErrorKind::Interrupted`] kind.
538545 ///
539546 /// If successful, this function will return the total number of bytes read.
540547 ///
541548 /// # Errors
542549 ///
543550 /// If this function encounters an error of the kind
544- /// `ErrorKind::Interrupted` then the error is ignored and the operation
551+ /// [ `ErrorKind::Interrupted`] then the error is ignored and the operation
545552 /// will continue.
546553 ///
547554 /// If any other read error is encountered then this function immediately
@@ -550,9 +557,12 @@ pub trait Read {
550557 ///
551558 /// # Examples
552559 ///
553- /// [`File`][file] s implement `Read`:
560+ /// [`File`]s implement `Read`:
554561 ///
555- /// [file]: ../fs/struct.File.html
562+ /// [`read()`]: trait.Read.html#tymethod.read
563+ /// [`Ok(0)`]: ../../std/result/enum.Result.html#variant.Ok
564+ /// [`ErrorKind::Interrupted`]: ../../std/io/enum.ErrorKind.html#variant.Interrupted
565+ /// [`File`]: ../fs/struct.File.html
556566 ///
557567 /// ```
558568 /// use std::io;
@@ -633,11 +643,11 @@ pub trait Read {
633643 /// # Errors
634644 ///
635645 /// If this function encounters an error of the kind
636- /// `ErrorKind::Interrupted` then the error is ignored and the operation
646+ /// [ `ErrorKind::Interrupted`] then the error is ignored and the operation
637647 /// will continue.
638648 ///
639649 /// If this function encounters an "end of file" before completely filling
640- /// the buffer, it returns an error of the kind `ErrorKind::UnexpectedEof`.
650+ /// the buffer, it returns an error of the kind [ `ErrorKind::UnexpectedEof`] .
641651 /// The contents of `buf` are unspecified in this case.
642652 ///
643653 /// If any other read error is encountered then this function immediately
@@ -649,9 +659,11 @@ pub trait Read {
649659 ///
650660 /// # Examples
651661 ///
652- /// [`File`][file] s implement `Read`:
662+ /// [`File`]s implement `Read`:
653663 ///
654- /// [file]: ../fs/struct.File.html
664+ /// [`File`]: ../fs/struct.File.html
665+ /// [`ErrorKind::Interrupted`]: ../../std/io/enum.ErrorKind.html#variant.Interrupted
666+ /// [`ErrorKind::UnexpectedEof`]: ../../std/io/enum.ErrorKind.html#variant.UnexpectedEof
655667 ///
656668 /// ```
657669 /// use std::io;
@@ -722,18 +734,24 @@ pub trait Read {
722734 #[ stable( feature = "rust1" , since = "1.0.0" ) ]
723735 fn by_ref ( & mut self ) -> & mut Self where Self : Sized { self }
724736
725- /// Transforms this `Read` instance to an `Iterator` over its bytes.
737+ /// Transforms this `Read` instance to an [ `Iterator`] over its bytes.
726738 ///
727- /// The returned type implements `Iterator` where the `Item` is `Result<u8 ,
728- /// R::Err>`. The yielded item is `Ok` if a byte was successfully read and
729- /// `Err` otherwise for I/O errors. EOF is mapped to returning `None` from
739+ /// The returned type implements [ `Iterator`] where the `Item` is [ `Result`]`<`[`u8`]` ,
740+ /// R::Err>`. The yielded item is [ `Ok`] if a byte was successfully read and
741+ /// [ `Err`] otherwise for I/O errors. EOF is mapped to returning [ `None`] from
730742 /// this iterator.
731743 ///
732744 /// # Examples
733745 ///
734746 /// [`File`][file]s implement `Read`:
735747 ///
736748 /// [file]: ../fs/struct.File.html
749+ /// [`Iterator`]: ../../std/iter/trait.Iterator.html
750+ /// [`Result`]: ../../std/result/enum.Result.html
751+ /// [`u8`]: ../../std/primitive.u8.html
752+ /// [`Ok`]: ../../std/result/enum.Result.html#variant.Ok
753+ /// [`Err`]: ../../std/result/enum.Result.html#variant.Err
754+ /// [`None`]: ../../std/option/enum.Option.html#variant.None
737755 ///
738756 /// ```
739757 /// use std::io;
@@ -754,22 +772,26 @@ pub trait Read {
754772 Bytes { inner : self }
755773 }
756774
757- /// Transforms this `Read` instance to an `Iterator` over `char`s.
775+ /// Transforms this `Read` instance to an [ `Iterator`] over [ `char`] s.
758776 ///
759777 /// This adaptor will attempt to interpret this reader as a UTF-8 encoded
760- /// sequence of characters. The returned iterator will return `None` once
778+ /// sequence of characters. The returned iterator will return [ `None`] once
761779 /// EOF is reached for this reader. Otherwise each element yielded will be a
762- /// `Result< char, E>` where `E` may contain information about what I/O error
780+ /// [ `Result`]`<`[` char`]` , E>` where `E` may contain information about what I/O error
763781 /// occurred or where decoding failed.
764782 ///
765783 /// Currently this adaptor will discard intermediate data read, and should
766784 /// be avoided if this is not desired.
767785 ///
768786 /// # Examples
769787 ///
770- /// [`File`][file] s implement `Read`:
788+ /// [`File`]s implement `Read`:
771789 ///
772- /// [file]: ../fs/struct.File.html
790+ /// [`File`]: ../fs/struct.File.html
791+ /// [`Iterator`]: ../../std/iter/trait.Iterator.html
792+ /// [`Result`]: ../../std/result/enum.Result.html
793+ /// [`char`]: ../../std/primitive.char.html
794+ /// [`None`]: ../../std/option/enum.Option.html#variant.None
773795 ///
774796 /// ```
775797 /// #![feature(io)]
@@ -832,15 +854,17 @@ pub trait Read {
832854 /// Creates an adaptor which will read at most `limit` bytes from it.
833855 ///
834856 /// This function returns a new instance of `Read` which will read at most
835- /// `limit` bytes, after which it will always return EOF (`Ok(0)`). Any
857+ /// `limit` bytes, after which it will always return EOF ([ `Ok(0)`] ). Any
836858 /// read errors will not count towards the number of bytes read and future
837- /// calls to `read` may succeed.
859+ /// calls to [ `read()`] may succeed.
838860 ///
839861 /// # Examples
840862 ///
841- /// [`File`][file] s implement `Read`:
863+ /// [`File`]s implement `Read`:
842864 ///
843- /// [file]: ../fs/struct.File.html
865+ /// [`File`]: ../fs/struct.File.html
866+ /// [`Ok(0)`]: ../../std/result/enum.Result.html#variant.Ok
867+ /// [`read()`]: trait.Read.html#tymethod.read
844868 ///
845869 /// ```
846870 /// use std::io;
0 commit comments