@@ -401,28 +401,29 @@ fn read_to_end<R: Read + ?Sized>(r: &mut R, buf: &mut Vec<u8>) -> Result<usize>
401
401
///
402
402
/// Implementors of the `Read` trait are called 'readers'.
403
403
///
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()`]
405
405
/// 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
407
407
/// implementors a number of ways to read bytes while only needing to implement
408
408
/// a single method.
409
409
///
410
410
/// 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`
412
412
/// trait.
413
413
///
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.
420
417
///
421
418
/// # Examples
422
419
///
423
- /// [`File`][file] s implement `Read`:
420
+ /// [`File`]s implement `Read`:
424
421
///
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
426
427
///
427
428
/// ```
428
429
/// use std::io;
@@ -455,9 +456,9 @@ pub trait Read {
455
456
///
456
457
/// This function does not provide any guarantees about whether it blocks
457
458
/// 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.
459
460
///
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
461
462
/// guaranteed that `0 <= n <= buf.len()`. A nonzero `n` value indicates
462
463
/// that the buffer `buf` has been filled in with `n` bytes of data from this
463
464
/// source. If `n` is `0`, then it can indicate one of two scenarios:
@@ -478,14 +479,17 @@ pub trait Read {
478
479
/// variant will be returned. If an error is returned then it must be
479
480
/// guaranteed that no bytes were read.
480
481
///
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
482
483
/// operation should be retried if there is nothing else to do.
483
484
///
484
485
/// # Examples
485
486
///
486
- /// [`File`][file] s implement `Read`:
487
+ /// [`File`]s implement `Read`:
487
488
///
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
489
493
///
490
494
/// ```
491
495
/// use std::io;
@@ -511,8 +515,8 @@ pub trait Read {
511
515
/// buffers.
512
516
///
513
517
/// 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.
516
520
///
517
521
/// The behavior of this method must be independent of the state of the
518
522
/// `Read`er - the method only takes `&self` so that it can be used through
@@ -523,6 +527,9 @@ pub trait Read {
523
527
/// This method is unsafe because a `Read`er could otherwise return a
524
528
/// non-zeroing `Initializer` from another `Read` type without an `unsafe`
525
529
/// block.
530
+ ///
531
+ /// [`Initializer::nop()`]: ../../std/io/struct.Initializer.html#method.nop
532
+ /// [`Initializer`]: ../../std/io/struct.Initializer.html
526
533
#[ unstable( feature = "read_initializer" , issue = "42788" ) ]
527
534
#[ inline]
528
535
unsafe fn initializer ( & self ) -> Initializer {
@@ -532,16 +539,16 @@ pub trait Read {
532
539
/// Read all bytes until EOF in this source, placing them into `buf`.
533
540
///
534
541
/// 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.
538
545
///
539
546
/// If successful, this function will return the total number of bytes read.
540
547
///
541
548
/// # Errors
542
549
///
543
550
/// 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
545
552
/// will continue.
546
553
///
547
554
/// If any other read error is encountered then this function immediately
@@ -550,9 +557,12 @@ pub trait Read {
550
557
///
551
558
/// # Examples
552
559
///
553
- /// [`File`][file] s implement `Read`:
560
+ /// [`File`]s implement `Read`:
554
561
///
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
556
566
///
557
567
/// ```
558
568
/// use std::io;
@@ -633,11 +643,11 @@ pub trait Read {
633
643
/// # Errors
634
644
///
635
645
/// 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
637
647
/// will continue.
638
648
///
639
649
/// 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`] .
641
651
/// The contents of `buf` are unspecified in this case.
642
652
///
643
653
/// If any other read error is encountered then this function immediately
@@ -649,9 +659,11 @@ pub trait Read {
649
659
///
650
660
/// # Examples
651
661
///
652
- /// [`File`][file] s implement `Read`:
662
+ /// [`File`]s implement `Read`:
653
663
///
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
655
667
///
656
668
/// ```
657
669
/// use std::io;
@@ -722,18 +734,24 @@ pub trait Read {
722
734
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
723
735
fn by_ref ( & mut self ) -> & mut Self where Self : Sized { self }
724
736
725
- /// Transforms this `Read` instance to an `Iterator` over its bytes.
737
+ /// Transforms this `Read` instance to an [ `Iterator`] over its bytes.
726
738
///
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
730
742
/// this iterator.
731
743
///
732
744
/// # Examples
733
745
///
734
746
/// [`File`][file]s implement `Read`:
735
747
///
736
748
/// [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
737
755
///
738
756
/// ```
739
757
/// use std::io;
@@ -754,22 +772,26 @@ pub trait Read {
754
772
Bytes { inner : self }
755
773
}
756
774
757
- /// Transforms this `Read` instance to an `Iterator` over `char`s.
775
+ /// Transforms this `Read` instance to an [ `Iterator`] over [ `char`] s.
758
776
///
759
777
/// 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
761
779
/// 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
763
781
/// occurred or where decoding failed.
764
782
///
765
783
/// Currently this adaptor will discard intermediate data read, and should
766
784
/// be avoided if this is not desired.
767
785
///
768
786
/// # Examples
769
787
///
770
- /// [`File`][file] s implement `Read`:
788
+ /// [`File`]s implement `Read`:
771
789
///
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
773
795
///
774
796
/// ```
775
797
/// #![feature(io)]
@@ -832,15 +854,17 @@ pub trait Read {
832
854
/// Creates an adaptor which will read at most `limit` bytes from it.
833
855
///
834
856
/// 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
836
858
/// 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.
838
860
///
839
861
/// # Examples
840
862
///
841
- /// [`File`][file] s implement `Read`:
863
+ /// [`File`]s implement `Read`:
842
864
///
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
844
868
///
845
869
/// ```
846
870
/// use std::io;
0 commit comments