From 5719d221252e5b541dfc3d6d6557f73875fc76b4 Mon Sep 17 00:00:00 2001 From: patrick-gu <55641350+patrick-gu@users.noreply.github.com> Date: Sun, 29 Aug 2021 12:29:43 -0700 Subject: [PATCH 1/4] Add links in docs for some primitive types --- library/core/src/array/mod.rs | 8 ++-- library/core/src/bool.rs | 4 +- library/core/src/char/methods.rs | 78 ++++++++++++++++--------------- library/std/src/primitive_docs.rs | 67 ++++++++++++++------------ 4 files changed, 85 insertions(+), 72 deletions(-) diff --git a/library/core/src/array/mod.rs b/library/core/src/array/mod.rs index 3c638e655dc91..a22bbb22287cb 100644 --- a/library/core/src/array/mod.rs +++ b/library/core/src/array/mod.rs @@ -310,9 +310,9 @@ impl [T; N] { /// on large arrays or check the emitted code. Also try to avoid chained /// maps (e.g. `arr.map(...).map(...)`). /// - /// In many cases, you can instead use [`Iterator::map`] by calling `.iter()` - /// or `.into_iter()` on your array. `[T; N]::map` is only necessary if you - /// really need a new array of the same size as the result. Rust's lazy + /// In many cases, you can instead use [`Iterator::map`] by calling [`.iter()`](slice::iter) + /// or [`.into_iter()`](IntoIterator::into_iter) on your array. `[T; N]::map` is only necessary + /// if you really need a new array of the same size as the result. Rust's lazy /// iterators tend to get optimized very well. /// /// @@ -396,7 +396,7 @@ impl [T; N] { /// /// This method is particularly useful if combined with other methods, like /// [`map`](#method.map). This way, you can avoid moving the original - /// array if its elements are not `Copy`. + /// array if its elements are not [`Copy`]. /// /// ``` /// #![feature(array_methods)] diff --git a/library/core/src/bool.rs b/library/core/src/bool.rs index dcafaae2f5b49..c95f7ae1694cd 100644 --- a/library/core/src/bool.rs +++ b/library/core/src/bool.rs @@ -2,7 +2,7 @@ #[lang = "bool"] impl bool { - /// Returns `Some(t)` if the `bool` is `true`, or `None` otherwise. + /// Returns [Some]\(t) if the `bool` is [`true`](keyword.true.html), or [`None`] otherwise. /// /// # Examples /// @@ -18,7 +18,7 @@ impl bool { if self { Some(t) } else { None } } - /// Returns `Some(f())` if the `bool` is `true`, or `None` otherwise. + /// Returns [Some]\(f()) if the `bool` is [`true`](keyword.true.html), or [`None`] otherwise. /// /// # Examples /// diff --git a/library/core/src/char/methods.rs b/library/core/src/char/methods.rs index 0dadbdd1bd054..46ceef13b1533 100644 --- a/library/core/src/char/methods.rs +++ b/library/core/src/char/methods.rs @@ -29,11 +29,11 @@ impl char { pub const REPLACEMENT_CHARACTER: char = '\u{FFFD}'; /// The version of [Unicode](https://www.unicode.org/) that the Unicode parts of - /// `char` and `str` methods are based on. + /// `char` and [`str`] methods are based on. /// /// New versions of Unicode are released regularly and subsequently all methods /// in the standard library depending on Unicode are updated. Therefore the - /// behavior of some `char` and `str` methods and the value of this constant + /// behavior of some `char` and [`str`] methods and the value of this constant /// changes over time. This is *not* considered to be a breaking change. /// /// The version numbering scheme is explained in @@ -42,7 +42,7 @@ impl char { pub const UNICODE_VERSION: (u8, u8, u8) = crate::unicode::UNICODE_VERSION; /// Creates an iterator over the UTF-16 encoded code points in `iter`, - /// returning unpaired surrogates as `Err`s. + /// returning unpaired surrogates as [`Err`]s. /// /// # Examples /// @@ -70,7 +70,7 @@ impl char { /// ); /// ``` /// - /// A lossy decoder can be obtained by replacing `Err` results with the replacement character: + /// A lossy decoder can be obtained by replacing [`Err`] results with the replacement character: /// /// ``` /// use std::char::{decode_utf16, REPLACEMENT_CHARACTER}; @@ -93,10 +93,10 @@ impl char { super::decode::decode_utf16(iter) } - /// Converts a `u32` to a `char`. + /// Converts a [`u32`] to a `char`. /// /// Note that all `char`s are valid [`u32`]s, and can be cast to one with - /// `as`: + /// [`as`](keyword.as.html): /// /// ``` /// let c = '💯'; @@ -106,7 +106,7 @@ impl char { /// ``` /// /// However, the reverse is not true: not all valid [`u32`]s are valid - /// `char`s. `from_u32()` will return `None` if the input is not a valid value + /// `char`s. `from_u32()` will return [`None`] if the input is not a valid value /// for a `char`. /// /// For an unsafe version of this function which ignores these checks, see @@ -126,7 +126,7 @@ impl char { /// assert_eq!(Some('❤'), c); /// ``` /// - /// Returning `None` when the input is not a valid `char`: + /// Returning [`None`] when the input is not a valid `char`: /// /// ``` /// use std::char; @@ -141,7 +141,7 @@ impl char { super::convert::from_u32(i) } - /// Converts a `u32` to a `char`, ignoring validity. + /// Converts a [`u32`] to a `char`, ignoring validity. /// /// Note that all `char`s are valid [`u32`]s, and can be cast to one with /// `as`: @@ -190,7 +190,7 @@ impl char { /// sixteen, hexadecimal, to give some common values. Arbitrary /// radices are supported. /// - /// `from_digit()` will return `None` if the input is not a digit in + /// `from_digit()` will return [`None`] if the input is not a digit in /// the given radix. /// /// # Panics @@ -214,7 +214,7 @@ impl char { /// assert_eq!(Some('b'), c); /// ``` /// - /// Returning `None` when the input is not a digit: + /// Returning [`None`] when the input is not a digit: /// /// ``` /// use std::char; @@ -299,7 +299,7 @@ impl char { /// /// # Errors /// - /// Returns `None` if the `char` does not refer to a digit in the given radix. + /// Returns [`None`] if the `char` does not refer to a digit in the given radix. /// /// # Panics /// @@ -360,7 +360,7 @@ impl char { /// println!(); /// ``` /// - /// Using `println!` directly: + /// Using [`println!`](macro.println.html) directly: /// /// ``` /// println!("{}", '❤'.escape_unicode()); @@ -372,7 +372,7 @@ impl char { /// println!("\\u{{2764}}"); /// ``` /// - /// Using `to_string`: + /// Using [`to_string`](string/trait.ToString.html#tymethod.to_string): /// /// ``` /// assert_eq!('❤'.escape_unicode().to_string(), "\\u{2764}"); @@ -422,8 +422,8 @@ impl char { /// Returns an iterator that yields the literal escape code of a character /// as `char`s. /// - /// This will escape the characters similar to the `Debug` implementations - /// of `str` or `char`. + /// This will escape the characters similar to the [`Debug`](core::fmt::Debug) implementations + /// of [`str`] or `char`. /// /// # Examples /// @@ -436,7 +436,7 @@ impl char { /// println!(); /// ``` /// - /// Using `println!` directly: + /// Using [`println!`](macro.println.html) directly: /// /// ``` /// println!("{}", '\n'.escape_debug()); @@ -448,7 +448,7 @@ impl char { /// println!("\\n"); /// ``` /// - /// Using `to_string`: + /// Using [`to_string`](string/trait.ToString.html#tymethod.to_string): /// /// ``` /// assert_eq!('\n'.escape_debug().to_string(), "\\n"); @@ -490,7 +490,7 @@ impl char { /// println!(); /// ``` /// - /// Using `println!` directly: + /// Using [`println!`](macro.println.html) directly: /// /// ``` /// println!("{}", '"'.escape_default()); @@ -502,7 +502,7 @@ impl char { /// println!("\\\""); /// ``` /// - /// Using `to_string`: + /// Using [`to_string`](string/trait.ToString.html#tymethod.to_string): /// /// ``` /// assert_eq!('"'.escape_default().to_string(), "\\\""); @@ -543,8 +543,9 @@ impl char { /// assert_eq!(len, 4); /// ``` /// - /// The `&str` type guarantees that its contents are UTF-8, and so we can compare the length it - /// would take if each code point was represented as a `char` vs in the `&str` itself: + /// The [&](reference)[str] type guarantees that its contents are UTF-8, + /// and so we can compare the length it would take if each code point was represented + /// as a `char` vs in the [&](reference)[str] itself: /// /// ``` /// // as chars @@ -637,7 +638,7 @@ impl char { unsafe { from_utf8_unchecked_mut(encode_utf8_raw(self as u32, dst)) } } - /// Encodes this character as UTF-16 into the provided `u16` buffer, + /// Encodes this character as UTF-16 into the provided [`u16`] buffer, /// and then returns the subslice of the buffer that contains the encoded character. /// /// # Panics @@ -647,7 +648,7 @@ impl char { /// /// # Examples /// - /// In both of these examples, '𝕊' takes two `u16`s to encode. + /// In both of these examples, '𝕊' takes two [`u16`]s to encode. /// /// ``` /// let mut b = [0; 2]; @@ -671,7 +672,7 @@ impl char { encode_utf16_raw(self as u32, dst) } - /// Returns `true` if this `char` has the `Alphabetic` property. + /// Returns [`true`](keyword.true.html) if this `char` has the `Alphabetic` property. /// /// `Alphabetic` is described in Chapter 4 (Character Properties) of the [Unicode Standard] and /// specified in the [Unicode Character Database][ucd] [`DerivedCoreProperties.txt`]. @@ -701,7 +702,7 @@ impl char { } } - /// Returns `true` if this `char` has the `Lowercase` property. + /// Returns [`true`](keyword.true.html) if this `char` has the `Lowercase` property. /// /// `Lowercase` is described in Chapter 4 (Character Properties) of the [Unicode Standard] and /// specified in the [Unicode Character Database][ucd] [`DerivedCoreProperties.txt`]. @@ -733,7 +734,7 @@ impl char { } } - /// Returns `true` if this `char` has the `Uppercase` property. + /// Returns [`true`](keyword.true.html) if this `char` has the `Uppercase` property. /// /// `Uppercase` is described in Chapter 4 (Character Properties) of the [Unicode Standard] and /// specified in the [Unicode Character Database][ucd] [`DerivedCoreProperties.txt`]. @@ -765,7 +766,7 @@ impl char { } } - /// Returns `true` if this `char` has the `White_Space` property. + /// Returns [`true`](keyword.true.html) if this `char` has the `White_Space` property. /// /// `White_Space` is specified in the [Unicode Character Database][ucd] [`PropList.txt`]. /// @@ -793,7 +794,8 @@ impl char { } } - /// Returns `true` if this `char` satisfies either [`is_alphabetic()`] or [`is_numeric()`]. + /// Returns [`true`](keyword.true.html) if this `char` satisfies either + /// [`is_alphabetic()`] or [`is_numeric()`]. /// /// [`is_alphabetic()`]: #method.is_alphabetic /// [`is_numeric()`]: #method.is_numeric @@ -818,7 +820,7 @@ impl char { self.is_alphabetic() || self.is_numeric() } - /// Returns `true` if this `char` has the general category for control codes. + /// Returns [`true`](keyword.true.html) if this `char` has the general category for control codes. /// /// Control codes (code points with the general category of `Cc`) are described in Chapter 4 /// (Character Properties) of the [Unicode Standard] and specified in the [Unicode Character @@ -843,7 +845,7 @@ impl char { unicode::Cc(self) } - /// Returns `true` if this `char` has the `Grapheme_Extend` property. + /// Returns [`true`](keyword.true.html) if this `char` has the `Grapheme_Extend` property. /// /// `Grapheme_Extend` is described in [Unicode Standard Annex #29 (Unicode Text /// Segmentation)][uax29] and specified in the [Unicode Character Database][ucd] @@ -857,7 +859,7 @@ impl char { unicode::Grapheme_Extend(self) } - /// Returns `true` if this `char` has one of the general categories for numbers. + /// Returns [`true`](keyword.true.html) if this `char` has one of the general categories for numbers. /// /// The general categories for numbers (`Nd` for decimal digits, `Nl` for letter-like numeric /// characters, and `No` for other numeric characters) are specified in the [Unicode Character @@ -925,7 +927,7 @@ impl char { /// println!(); /// ``` /// - /// Using `println!` directly: + /// Using [`println!`](macro.println.html) directly: /// /// ``` /// println!("{}", 'İ'.to_lowercase()); @@ -937,7 +939,7 @@ impl char { /// println!("i\u{307}"); /// ``` /// - /// Using `to_string`: + /// Using [`to_string`](string/trait.ToString.html#tymethod.to_string): /// /// ``` /// assert_eq!('C'.to_lowercase().to_string(), "c"); @@ -990,7 +992,7 @@ impl char { /// println!(); /// ``` /// - /// Using `println!` directly: + /// Using [`println!`](macro.println.html) directly: /// /// ``` /// println!("{}", 'ß'.to_uppercase()); @@ -1002,7 +1004,7 @@ impl char { /// println!("SS"); /// ``` /// - /// Using `to_string`: + /// Using [`to_string`](string/trait.ToString.html#tymethod.to_string): /// /// ``` /// assert_eq!('c'.to_uppercase().to_string(), "C"); @@ -1131,7 +1133,7 @@ impl char { /// Checks that two values are an ASCII case-insensitive match. /// - /// Equivalent to `to_ascii_lowercase(a) == to_ascii_lowercase(b)`. + /// Equivalent to [to_ascii_lowercase]\(a) == [to_ascii_lowercase]\(b). /// /// # Examples /// @@ -1144,6 +1146,8 @@ impl char { /// assert!(upper_a.eq_ignore_ascii_case(&upper_a)); /// assert!(!upper_a.eq_ignore_ascii_case(&lower_z)); /// ``` + /// + /// [to_ascii_lowercase]: #method.to_ascii_lowercase #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")] #[inline] diff --git a/library/std/src/primitive_docs.rs b/library/std/src/primitive_docs.rs index dc4572cd9363b..1c02f49d15ccd 100644 --- a/library/std/src/primitive_docs.rs +++ b/library/std/src/primitive_docs.rs @@ -3,16 +3,16 @@ #[doc(alias = "false")] /// The boolean type. /// -/// The `bool` represents a value, which could only be either `true` or `false`. If you cast -/// a `bool` into an integer, `true` will be 1 and `false` will be 0. +/// The `bool` represents a value, which could only be either [`true`] or [`false`]. If you cast +/// a `bool` into an integer, [`true`] will be 1 and [`false`] will be 0. /// /// # Basic usage /// /// `bool` implements various traits, such as [`BitAnd`], [`BitOr`], [`Not`], etc., /// which allow us to perform boolean operations using `&`, `|` and `!`. /// -/// `if` requires a `bool` value as its conditional. [`assert!`], which is an -/// important macro in testing, checks whether an expression is `true` and panics +/// [`if`] requires a `bool` value as its conditional. [`assert!`], which is an +/// important macro in testing, checks whether an expression is [`true`] and panics /// if it isn't. /// /// ``` @@ -20,9 +20,12 @@ /// assert!(!bool_val); /// ``` /// +/// [`true`]: keyword.true.html +/// [`false`]: keyword.false.html /// [`BitAnd`]: ops::BitAnd /// [`BitOr`]: ops::BitOr /// [`Not`]: ops::Not +/// [`if`]: keyword.if.html /// /// # Examples /// @@ -574,11 +577,11 @@ mod prim_pointer {} /// /// # Editions /// -/// Prior to Rust 1.53, arrays did not implement `IntoIterator` by value, so the method call -/// `array.into_iter()` auto-referenced into a slice iterator. Right now, the old behavior -/// is preserved in the 2015 and 2018 editions of Rust for compatibility, ignoring -/// `IntoIterator` by value. In the future, the behavior on the 2015 and 2018 edition -/// might be made consistent to the behavior of later editions. +/// Prior to Rust 1.53, arrays did not implement [`IntoIterator`] by value, so the method call +/// array.[into_iter()] auto-referenced into a slice iterator. +/// Right now, the old behavior is preserved in the 2015 and 2018 editions of Rust for +/// compatibility, ignoring [`IntoIterator`] by value. In the future, the behavior on the 2015 and +/// 2018 edition might be made consistent to the behavior of later editions. /// /// ```rust,edition2018 /// # #![allow(array_into_iter)] // override our `deny(warnings)` @@ -604,8 +607,9 @@ mod prim_pointer {} /// } /// ``` /// -/// Starting in the 2021 edition, `array.into_iter()` will use `IntoIterator` normally to iterate -/// by value, and `iter()` should be used to iterate by reference like previous editions. +/// Starting in the 2021 edition, array.[into_iter()] will use [`IntoIterator`] +/// normally to iterate by value, and [`iter()`](slice::iter) should be used to iterate by +/// reference like previous editions. /// /// ```rust,edition2021,ignore /// # // FIXME: ignored because 2021 testing is still unstable @@ -624,16 +628,16 @@ mod prim_pointer {} /// } /// ``` /// -/// Future language versions might start treating the `array.into_iter()` +/// Future language versions might start treating the array.[into_iter()] /// syntax on editions 2015 and 2018 the same as on edition 2021. So code using /// those older editions should still be written with this change in mind, to /// prevent breakage in the future. The safest way to accomplish this is to -/// avoid the `into_iter` syntax on those editions. If an edition update is not -/// viable/desired, there are multiple alternatives: -/// * use `iter`, equivalent to the old behavior, creating references +/// avoid the [`into_iter`](IntoIterator::into_iter) syntax on those editions. +/// If an edition update is not viable/desired, there are multiple alternatives: +/// * use [`iter`](slice::iter), equivalent to the old behavior, creating references /// * use [`array::IntoIter`], equivalent to the post-2021 behavior (Rust 1.51+) -/// * replace `for ... in array.into_iter() {` with `for ... in array {`, -/// equivalent to the post-2021 behavior (Rust 1.53+) +/// * replace [for] ... [in] array.[into_iter()] {` with +/// [for] ... [in] array {, equivalent to the post-2021 behavior (Rust 1.53+) /// /// ```rust,edition2018 /// use std::array::IntoIter; @@ -672,6 +676,9 @@ mod prim_pointer {} /// [`Borrow`]: borrow::Borrow /// [`BorrowMut`]: borrow::BorrowMut /// [slice pattern]: ../reference/patterns.html#slice-patterns +/// [into_iter()]: IntoIterator::into_iter +/// [for]: keyword.for.html +/// [in]: keyword.in.html #[stable(feature = "rust1", since = "1.0.0")] mod prim_array {} @@ -829,7 +836,7 @@ mod prim_str {} /// ``` /// /// The sequential nature of the tuple applies to its implementations of various -/// traits. For example, in `PartialOrd` and `Ord`, the elements are compared +/// traits. For example, in [`PartialOrd`] and [`Ord`], the elements are compared /// sequentially until the first non-equal set is found. /// /// For more about tuples, see [the book](../book/ch03-02-data-types.html#the-tuple-type). @@ -1033,14 +1040,16 @@ mod prim_usize {} /// References, both shared and mutable. /// /// A reference represents a borrow of some owned value. You can get one by using the `&` or `&mut` -/// operators on a value, or by using a `ref` or `ref mut` pattern. +/// operators on a value, or by using a [`ref`](keyword.ref.html) or +/// [ref](keyword.ref.html) [mut](keyword.mut.html) pattern. /// /// For those familiar with pointers, a reference is just a pointer that is assumed to be /// aligned, not null, and pointing to memory containing a valid value of `T` - for example, -/// `&bool` can only point to an allocation containing the integer values `1` (`true`) or `0` -/// (`false`), but creating a `&bool` that points to an allocation containing -/// the value `3` causes undefined behaviour. -/// In fact, `Option<&T>` has the same memory representation as a +/// &[bool] can only point to an allocation containing the integer values `1` +/// ([`true`](keyword.true.html)) or `0` ([`false`](keyword.false.html)), but creating a +/// &[bool] that points to an allocation containing the value `3` causes +/// undefined behaviour. +/// In fact, [Option]\<&T> has the same memory representation as a /// nullable but aligned pointer, and can be passed across FFI boundaries as such. /// /// In most cases, references can be used much like the original value. Field access, method @@ -1088,7 +1097,7 @@ mod prim_usize {} /// The following traits are implemented for all `&T`, regardless of the type of its referent: /// /// * [`Copy`] -/// * [`Clone`] \(Note that this will not defer to `T`'s `Clone` implementation if it exists!) +/// * [`Clone`] \(Note that this will not defer to `T`'s [`Clone`] implementation if it exists!) /// * [`Deref`] /// * [`Borrow`] /// * [`Pointer`] @@ -1097,7 +1106,7 @@ mod prim_usize {} /// [`Borrow`]: borrow::Borrow /// [`Pointer`]: fmt::Pointer /// -/// `&mut T` references get all of the above except `Copy` and `Clone` (to prevent creating +/// `&mut T` references get all of the above except [`Copy`] and [`Clone`] (to prevent creating /// multiple simultaneous mutable borrows), plus the following, regardless of the type of its /// referent: /// @@ -1125,18 +1134,18 @@ mod prim_usize {} /// [`Hash`]: hash::Hash /// [`ToSocketAddrs`]: net::ToSocketAddrs /// -/// `&mut T` references get all of the above except `ToSocketAddrs`, plus the following, if `T` +/// `&mut T` references get all of the above except [`ToSocketAddrs`], plus the following, if `T` /// implements that trait: /// /// * [`AsMut`] -/// * [`FnMut`] \(in addition, `&mut T` references get [`FnOnce`] if `T: FnMut`) +/// * [`FnMut`] \(in addition, `&mut T` references get [`FnOnce`] if T: [FnMut]) /// * [`fmt::Write`] /// * [`Iterator`] /// * [`DoubleEndedIterator`] /// * [`ExactSizeIterator`] /// * [`FusedIterator`] /// * [`TrustedLen`] -/// * [`Send`] \(note that `&T` references only get `Send` if `T: Sync`) +/// * [`Send`] \(note that `&T` references only get [`Send`] if T: [Sync]) /// * [`io::Write`] /// * [`Read`] /// * [`Seek`] @@ -1168,7 +1177,7 @@ mod prim_ref {} /// Function pointers are pointers that point to *code*, not data. They can be called /// just like functions. Like references, function pointers are, among other things, assumed to /// not be null, so if you want to pass a function pointer over FFI and be able to accommodate null -/// pointers, make your type `Option` with your required signature. +/// pointers, make your type [Option]\ with your required signature. /// /// ### Safety /// From 911d0cbe8092d03dcb77fb7df03191691f5d0092 Mon Sep 17 00:00:00 2001 From: patrick-gu <55641350+patrick-gu@users.noreply.github.com> Date: Fri, 3 Sep 2021 17:09:37 -0700 Subject: [PATCH 2/4] Remove excessive linking --- library/core/src/array/mod.rs | 6 ++-- library/core/src/bool.rs | 4 +-- library/core/src/char/methods.rs | 60 +++++++++++++++---------------- library/std/src/primitive_docs.rs | 41 ++++++++++----------- 4 files changed, 53 insertions(+), 58 deletions(-) diff --git a/library/core/src/array/mod.rs b/library/core/src/array/mod.rs index a22bbb22287cb..cc74c1b96f4ed 100644 --- a/library/core/src/array/mod.rs +++ b/library/core/src/array/mod.rs @@ -310,9 +310,9 @@ impl [T; N] { /// on large arrays or check the emitted code. Also try to avoid chained /// maps (e.g. `arr.map(...).map(...)`). /// - /// In many cases, you can instead use [`Iterator::map`] by calling [`.iter()`](slice::iter) - /// or [`.into_iter()`](IntoIterator::into_iter) on your array. `[T; N]::map` is only necessary - /// if you really need a new array of the same size as the result. Rust's lazy + /// In many cases, you can instead use [`Iterator::map`] by calling `.iter()` + /// or `.into_iter()` on your array. `[T; N]::map` is only necessary if you + /// really need a new array of the same size as the result. Rust's lazy /// iterators tend to get optimized very well. /// /// diff --git a/library/core/src/bool.rs b/library/core/src/bool.rs index c95f7ae1694cd..4a01234720164 100644 --- a/library/core/src/bool.rs +++ b/library/core/src/bool.rs @@ -2,7 +2,7 @@ #[lang = "bool"] impl bool { - /// Returns [Some]\(t) if the `bool` is [`true`](keyword.true.html), or [`None`] otherwise. + /// Returns `Some(t)` if the `bool` is [`true`](keyword.true.html), or `None` otherwise. /// /// # Examples /// @@ -18,7 +18,7 @@ impl bool { if self { Some(t) } else { None } } - /// Returns [Some]\(f()) if the `bool` is [`true`](keyword.true.html), or [`None`] otherwise. + /// Returns `Some` if the `bool` is [`true`](keyword.true.html), or `None` otherwise. /// /// # Examples /// diff --git a/library/core/src/char/methods.rs b/library/core/src/char/methods.rs index 46ceef13b1533..7e545e2b098d8 100644 --- a/library/core/src/char/methods.rs +++ b/library/core/src/char/methods.rs @@ -29,11 +29,11 @@ impl char { pub const REPLACEMENT_CHARACTER: char = '\u{FFFD}'; /// The version of [Unicode](https://www.unicode.org/) that the Unicode parts of - /// `char` and [`str`] methods are based on. + /// `char` and `str` methods are based on. /// /// New versions of Unicode are released regularly and subsequently all methods /// in the standard library depending on Unicode are updated. Therefore the - /// behavior of some `char` and [`str`] methods and the value of this constant + /// behavior of some `char` and `str` methods and the value of this constant /// changes over time. This is *not* considered to be a breaking change. /// /// The version numbering scheme is explained in @@ -42,7 +42,7 @@ impl char { pub const UNICODE_VERSION: (u8, u8, u8) = crate::unicode::UNICODE_VERSION; /// Creates an iterator over the UTF-16 encoded code points in `iter`, - /// returning unpaired surrogates as [`Err`]s. + /// returning unpaired surrogates as `Err`s. /// /// # Examples /// @@ -70,7 +70,7 @@ impl char { /// ); /// ``` /// - /// A lossy decoder can be obtained by replacing [`Err`] results with the replacement character: + /// A lossy decoder can be obtained by replacing `Err` results with the replacement character: /// /// ``` /// use std::char::{decode_utf16, REPLACEMENT_CHARACTER}; @@ -93,7 +93,7 @@ impl char { super::decode::decode_utf16(iter) } - /// Converts a [`u32`] to a `char`. + /// Converts a `u32` to a `char`. /// /// Note that all `char`s are valid [`u32`]s, and can be cast to one with /// [`as`](keyword.as.html): @@ -106,7 +106,7 @@ impl char { /// ``` /// /// However, the reverse is not true: not all valid [`u32`]s are valid - /// `char`s. `from_u32()` will return [`None`] if the input is not a valid value + /// `char`s. `from_u32()` will return `None` if the input is not a valid value /// for a `char`. /// /// For an unsafe version of this function which ignores these checks, see @@ -126,7 +126,7 @@ impl char { /// assert_eq!(Some('❤'), c); /// ``` /// - /// Returning [`None`] when the input is not a valid `char`: + /// Returning `None` when the input is not a valid `char`: /// /// ``` /// use std::char; @@ -141,7 +141,7 @@ impl char { super::convert::from_u32(i) } - /// Converts a [`u32`] to a `char`, ignoring validity. + /// Converts a `u32` to a `char`, ignoring validity. /// /// Note that all `char`s are valid [`u32`]s, and can be cast to one with /// `as`: @@ -190,7 +190,7 @@ impl char { /// sixteen, hexadecimal, to give some common values. Arbitrary /// radices are supported. /// - /// `from_digit()` will return [`None`] if the input is not a digit in + /// `from_digit()` will return `None` if the input is not a digit in /// the given radix. /// /// # Panics @@ -214,7 +214,7 @@ impl char { /// assert_eq!(Some('b'), c); /// ``` /// - /// Returning [`None`] when the input is not a digit: + /// Returning `None` when the input is not a digit: /// /// ``` /// use std::char; @@ -299,7 +299,7 @@ impl char { /// /// # Errors /// - /// Returns [`None`] if the `char` does not refer to a digit in the given radix. + /// Returns `None` if the `char` does not refer to a digit in the given radix. /// /// # Panics /// @@ -360,7 +360,7 @@ impl char { /// println!(); /// ``` /// - /// Using [`println!`](macro.println.html) directly: + /// Using `println! directly: /// /// ``` /// println!("{}", '❤'.escape_unicode()); @@ -423,7 +423,7 @@ impl char { /// as `char`s. /// /// This will escape the characters similar to the [`Debug`](core::fmt::Debug) implementations - /// of [`str`] or `char`. + /// of `str` or `char`. /// /// # Examples /// @@ -436,7 +436,7 @@ impl char { /// println!(); /// ``` /// - /// Using [`println!`](macro.println.html) directly: + /// Using `println!` directly: /// /// ``` /// println!("{}", '\n'.escape_debug()); @@ -490,7 +490,7 @@ impl char { /// println!(); /// ``` /// - /// Using [`println!`](macro.println.html) directly: + /// Using `println!` directly: /// /// ``` /// println!("{}", '"'.escape_default()); @@ -543,9 +543,8 @@ impl char { /// assert_eq!(len, 4); /// ``` /// - /// The [&](reference)[str] type guarantees that its contents are UTF-8, - /// and so we can compare the length it would take if each code point was represented - /// as a `char` vs in the [&](reference)[str] itself: + /// The `&str` type guarantees that its contents are UTF-8, and so we can compare the length it + /// would take if each code point was represented as a `char` vs in the `&str` itself: /// /// ``` /// // as chars @@ -638,7 +637,7 @@ impl char { unsafe { from_utf8_unchecked_mut(encode_utf8_raw(self as u32, dst)) } } - /// Encodes this character as UTF-16 into the provided [`u16`] buffer, + /// Encodes this character as UTF-16 into the provided `u16` buffer, /// and then returns the subslice of the buffer that contains the encoded character. /// /// # Panics @@ -648,7 +647,7 @@ impl char { /// /// # Examples /// - /// In both of these examples, '𝕊' takes two [`u16`]s to encode. + /// In both of these examples, '𝕊' takes two `u16`s to encode. /// /// ``` /// let mut b = [0; 2]; @@ -672,7 +671,7 @@ impl char { encode_utf16_raw(self as u32, dst) } - /// Returns [`true`](keyword.true.html) if this `char` has the `Alphabetic` property. + /// Returns `true` if this `char` has the `Alphabetic` property. /// /// `Alphabetic` is described in Chapter 4 (Character Properties) of the [Unicode Standard] and /// specified in the [Unicode Character Database][ucd] [`DerivedCoreProperties.txt`]. @@ -702,7 +701,7 @@ impl char { } } - /// Returns [`true`](keyword.true.html) if this `char` has the `Lowercase` property. + /// Returns `true` if this `char` has the `Lowercase` property. /// /// `Lowercase` is described in Chapter 4 (Character Properties) of the [Unicode Standard] and /// specified in the [Unicode Character Database][ucd] [`DerivedCoreProperties.txt`]. @@ -734,7 +733,7 @@ impl char { } } - /// Returns [`true`](keyword.true.html) if this `char` has the `Uppercase` property. + /// Returns `true` if this `char` has the `Uppercase` property. /// /// `Uppercase` is described in Chapter 4 (Character Properties) of the [Unicode Standard] and /// specified in the [Unicode Character Database][ucd] [`DerivedCoreProperties.txt`]. @@ -766,7 +765,7 @@ impl char { } } - /// Returns [`true`](keyword.true.html) if this `char` has the `White_Space` property. + /// Returns `true` if this `char` has the `White_Space` property. /// /// `White_Space` is specified in the [Unicode Character Database][ucd] [`PropList.txt`]. /// @@ -794,8 +793,7 @@ impl char { } } - /// Returns [`true`](keyword.true.html) if this `char` satisfies either - /// [`is_alphabetic()`] or [`is_numeric()`]. + /// Returns `true` if this `char` satisfies either [`is_alphabetic()`] or [`is_numeric()`]. /// /// [`is_alphabetic()`]: #method.is_alphabetic /// [`is_numeric()`]: #method.is_numeric @@ -820,7 +818,7 @@ impl char { self.is_alphabetic() || self.is_numeric() } - /// Returns [`true`](keyword.true.html) if this `char` has the general category for control codes. + /// Returns `true` if this `char` has the general category for control codes. /// /// Control codes (code points with the general category of `Cc`) are described in Chapter 4 /// (Character Properties) of the [Unicode Standard] and specified in the [Unicode Character @@ -845,7 +843,7 @@ impl char { unicode::Cc(self) } - /// Returns [`true`](keyword.true.html) if this `char` has the `Grapheme_Extend` property. + /// Returns `true` if this `char` has the `Grapheme_Extend` property. /// /// `Grapheme_Extend` is described in [Unicode Standard Annex #29 (Unicode Text /// Segmentation)][uax29] and specified in the [Unicode Character Database][ucd] @@ -859,7 +857,7 @@ impl char { unicode::Grapheme_Extend(self) } - /// Returns [`true`](keyword.true.html) if this `char` has one of the general categories for numbers. + /// Returns `true` if this `char` has one of the general categories for numbers. /// /// The general categories for numbers (`Nd` for decimal digits, `Nl` for letter-like numeric /// characters, and `No` for other numeric characters) are specified in the [Unicode Character @@ -927,7 +925,7 @@ impl char { /// println!(); /// ``` /// - /// Using [`println!`](macro.println.html) directly: + /// Using `println!` directly: /// /// ``` /// println!("{}", 'İ'.to_lowercase()); @@ -992,7 +990,7 @@ impl char { /// println!(); /// ``` /// - /// Using [`println!`](macro.println.html) directly: + /// Using `println!` directly: /// /// ``` /// println!("{}", 'ß'.to_uppercase()); diff --git a/library/std/src/primitive_docs.rs b/library/std/src/primitive_docs.rs index 1c02f49d15ccd..a4e39fb0e38a6 100644 --- a/library/std/src/primitive_docs.rs +++ b/library/std/src/primitive_docs.rs @@ -578,10 +578,10 @@ mod prim_pointer {} /// # Editions /// /// Prior to Rust 1.53, arrays did not implement [`IntoIterator`] by value, so the method call -/// array.[into_iter()] auto-referenced into a slice iterator. -/// Right now, the old behavior is preserved in the 2015 and 2018 editions of Rust for -/// compatibility, ignoring [`IntoIterator`] by value. In the future, the behavior on the 2015 and -/// 2018 edition might be made consistent to the behavior of later editions. +/// `array.into_iter()` auto-referenced into a [slice iterator](slice::iter). Right now, the old behavior +/// is preserved in the 2015 and 2018 editions of Rust for compatibility, ignoring +/// `IntoIterator` by value. In the future, the behavior on the 2015 and 2018 edition +/// might be made consistent to the behavior of later editions. /// /// ```rust,edition2018 /// # #![allow(array_into_iter)] // override our `deny(warnings)` @@ -607,9 +607,8 @@ mod prim_pointer {} /// } /// ``` /// -/// Starting in the 2021 edition, array.[into_iter()] will use [`IntoIterator`] -/// normally to iterate by value, and [`iter()`](slice::iter) should be used to iterate by -/// reference like previous editions. +/// Starting in the 2021 edition, `array.into_iter()` will use `IntoIterator` normally to iterate +/// by value, and `iter()` should be used to iterate by reference like previous editions. /// /// ```rust,edition2021,ignore /// # // FIXME: ignored because 2021 testing is still unstable @@ -628,16 +627,16 @@ mod prim_pointer {} /// } /// ``` /// -/// Future language versions might start treating the array.[into_iter()] +/// Future language versions might start treating the `array.into_iter()` /// syntax on editions 2015 and 2018 the same as on edition 2021. So code using /// those older editions should still be written with this change in mind, to /// prevent breakage in the future. The safest way to accomplish this is to -/// avoid the [`into_iter`](IntoIterator::into_iter) syntax on those editions. -/// If an edition update is not viable/desired, there are multiple alternatives: -/// * use [`iter`](slice::iter), equivalent to the old behavior, creating references +/// avoid the `into_iter` syntax on those editions. If an edition update is not +/// viable/desired, there are multiple alternatives: +/// * use `iter`, equivalent to the old behavior, creating references /// * use [`array::IntoIter`], equivalent to the post-2021 behavior (Rust 1.51+) -/// * replace [for] ... [in] array.[into_iter()] {` with -/// [for] ... [in] array {, equivalent to the post-2021 behavior (Rust 1.53+) +/// * replace `for ... in array.into_iter() {` with `for ... in array {`, +/// equivalent to the post-2021 behavior (Rust 1.53+) /// /// ```rust,edition2018 /// use std::array::IntoIter; @@ -676,9 +675,6 @@ mod prim_pointer {} /// [`Borrow`]: borrow::Borrow /// [`BorrowMut`]: borrow::BorrowMut /// [slice pattern]: ../reference/patterns.html#slice-patterns -/// [into_iter()]: IntoIterator::into_iter -/// [for]: keyword.for.html -/// [in]: keyword.in.html #[stable(feature = "rust1", since = "1.0.0")] mod prim_array {} @@ -1097,7 +1093,7 @@ mod prim_usize {} /// The following traits are implemented for all `&T`, regardless of the type of its referent: /// /// * [`Copy`] -/// * [`Clone`] \(Note that this will not defer to `T`'s [`Clone`] implementation if it exists!) +/// * [`Clone`] \(Note that this will not defer to `T`'s `Clone` implementation if it exists!) /// * [`Deref`] /// * [`Borrow`] /// * [`Pointer`] @@ -1106,7 +1102,7 @@ mod prim_usize {} /// [`Borrow`]: borrow::Borrow /// [`Pointer`]: fmt::Pointer /// -/// `&mut T` references get all of the above except [`Copy`] and [`Clone`] (to prevent creating +/// `&mut T` references get all of the above except `Copy` and `Clone` (to prevent creating /// multiple simultaneous mutable borrows), plus the following, regardless of the type of its /// referent: /// @@ -1134,18 +1130,18 @@ mod prim_usize {} /// [`Hash`]: hash::Hash /// [`ToSocketAddrs`]: net::ToSocketAddrs /// -/// `&mut T` references get all of the above except [`ToSocketAddrs`], plus the following, if `T` +/// `&mut T` references get all of the above except `ToSocketAddrs`, plus the following, if `T` /// implements that trait: /// /// * [`AsMut`] -/// * [`FnMut`] \(in addition, `&mut T` references get [`FnOnce`] if T: [FnMut]) +/// * [`FnMut`] \(in addition, `&mut T` references get [`FnOnce`] if `T: FnMut`) /// * [`fmt::Write`] /// * [`Iterator`] /// * [`DoubleEndedIterator`] /// * [`ExactSizeIterator`] /// * [`FusedIterator`] /// * [`TrustedLen`] -/// * [`Send`] \(note that `&T` references only get [`Send`] if T: [Sync]) +/// * [`Send`] \(note that `&T` references only get `Send` if T: [Sync]) /// * [`io::Write`] /// * [`Read`] /// * [`Seek`] @@ -1177,7 +1173,8 @@ mod prim_ref {} /// Function pointers are pointers that point to *code*, not data. They can be called /// just like functions. Like references, function pointers are, among other things, assumed to /// not be null, so if you want to pass a function pointer over FFI and be able to accommodate null -/// pointers, make your type [Option]\ with your required signature. +/// pointers, make your type [`Option`](core::option#options-and-pointers-nullable-pointers) +/// with your required signature. /// /// ### Safety /// From 529abb2fc0895b78c0f2763e4ce0413d889712c2 Mon Sep 17 00:00:00 2001 From: patrick-gu <55641350+patrick-gu@users.noreply.github.com> Date: Fri, 3 Sep 2021 17:11:57 -0700 Subject: [PATCH 3/4] Add a missing backtick --- library/core/src/char/methods.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/core/src/char/methods.rs b/library/core/src/char/methods.rs index 7e545e2b098d8..e6d3ac8f2d2c5 100644 --- a/library/core/src/char/methods.rs +++ b/library/core/src/char/methods.rs @@ -360,7 +360,7 @@ impl char { /// println!(); /// ``` /// - /// Using `println! directly: + /// Using `println!` directly: /// /// ``` /// println!("{}", '❤'.escape_unicode()); From 7c32b58df24fe98dd3529d344fec6b1ad1631b63 Mon Sep 17 00:00:00 2001 From: patrick-gu <55641350+patrick-gu@users.noreply.github.com> Date: Fri, 3 Sep 2021 17:13:42 -0700 Subject: [PATCH 4/4] Fix accidentally deleted part --- library/core/src/bool.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/core/src/bool.rs b/library/core/src/bool.rs index 4a01234720164..ca1c0ae759892 100644 --- a/library/core/src/bool.rs +++ b/library/core/src/bool.rs @@ -18,7 +18,7 @@ impl bool { if self { Some(t) } else { None } } - /// Returns `Some` if the `bool` is [`true`](keyword.true.html), or `None` otherwise. + /// Returns `Some(f())` if the `bool` is [`true`](keyword.true.html), or `None` otherwise. /// /// # Examples ///