Skip to content

Commit a2e79a7

Browse files
committed
Add more links to ! doc text
1 parent afd094a commit a2e79a7

File tree

1 file changed

+28
-18
lines changed

1 file changed

+28
-18
lines changed

src/libstd/primitive_docs.rs

+28-18
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ mod prim_bool { }
7676
/// so returns `!`.
7777
///
7878
/// `break`, `continue` and `return` expressions also have type `!`. For example we are allowed to
79-
/// write
79+
/// write:
8080
///
8181
/// ```
8282
/// # #![feature(never_type)]
@@ -104,10 +104,11 @@ mod prim_bool { }
104104
/// # }
105105
/// ```
106106
///
107-
/// Both match arms must produce values of type `u32`, but since `break` never produces a value at
108-
/// all we know it can never produce a value which isn't a `u32`. This illustrates another
107+
/// Both match arms must produce values of type [`u32`], but since `break` never produces a value
108+
/// at all we know it can never produce a value which isn't a [`u32`]. This illustrates another
109109
/// behaviour of the `!` type - expressions with type `!` will coerce into any other type.
110110
///
111+
/// [`u32`]: primitive.str.html
111112
/// [`exit`]: process/fn.exit.html
112113
///
113114
/// # `!` and generics
@@ -122,21 +123,27 @@ mod prim_bool { }
122123
/// }
123124
/// ```
124125
///
125-
/// When implementing this trait for `String` we need to pick a type for `Err`. And since
126+
/// When implementing this trait for [`String`] we need to pick a type for [`Err`]. And since
126127
/// converting a string into a string will never result in an error, the appropriate type is `!`.
127128
/// (Currently the type actually used is an enum with no variants, though this is only because `!`
128-
/// was added to Rust at a later date and it may change in the future). With an `Err` type of `!`,
129-
/// if we have to call `String::from_str` for some reason the result will be a `Result<String, !>`
130-
/// which we can unpack like this:
129+
/// was added to Rust at a later date and it may change in the future). With an [`Err`] type of
130+
/// `!`, if we have to call [`String::from_str`] for some reason the result will be a
131+
/// [`Result<String, !>`] which we can unpack like this:
131132
///
132133
/// ```ignore (string-from-str-error-type-is-not-never-yet)
133134
/// let Ok(s) = String::from_str("hello");
134135
/// ```
135136
///
136-
/// Since the `Err` variant contains a `!`, it can never occur. So we can exhaustively match on
137-
/// `Result<T, !>` by just taking the `Ok` variant. This illustrates another behaviour of `!` - it
138-
/// can be used to "delete" certain enum variants from generic types like `Result`.
137+
/// Since the [`Err`] variant contains a `!`, it can never occur. So we can exhaustively match on
138+
/// [`Result<T, !>`] by just taking the [`Ok`] variant. This illustrates another behaviour of `!` -
139+
/// it can be used to "delete" certain enum variants from generic types like `Result`.
139140
///
141+
/// [`String::from_str`]: str/trait.FromStr.html#tymethod.from_str
142+
/// [`Result<String, !>`]: result/enum.Result.html
143+
/// [`Result<T, !>`]: result/enum.Result.html
144+
/// [`Ok`]: result/enum.Result.html#variant.Ok
145+
/// [`String`]: string/struct.String.html
146+
/// [`Err`]: result/enum.Result.html#variant.Err
140147
/// [`FromStr`]: str/trait.FromStr.html
141148
///
142149
/// # `!` and traits
@@ -158,13 +165,13 @@ mod prim_bool { }
158165
/// }
159166
/// ```
160167
///
161-
/// Once again we're using `!`'s ability to coerce into any other type, in this case `fmt::Result`.
162-
/// Since this method takes a `&!` as an argument we know that it can never be called (because
163-
/// there is no value of type `!` for it to be called with). Writing `*self` essentially tells the
164-
/// compiler "We know that this code can never be run, so just treat the entire function body has
165-
/// having type `fmt::Result`". This pattern can be used a lot when implementing traits for `!`.
166-
/// Generally, any trait which only has methods which take a `self` parameter should have such as
167-
/// impl.
168+
/// Once again we're using `!`'s ability to coerce into any other type, in this case
169+
/// [`fmt::Result`]. Since this method takes a `&!` as an argument we know that it can never be
170+
/// called (because there is no value of type `!` for it to be called with). Writing `*self`
171+
/// essentially tells the compiler "We know that this code can never be run, so just treat the
172+
/// entire function body has having type [`fmt::Result`]". This pattern can be used a lot when
173+
/// implementing traits for `!`. Generally, any trait which only has methods which take a `self`
174+
/// parameter should have such as impl.
168175
///
169176
/// On the other hand, one trait which would not be appropriate to implement is [`Default`]:
170177
///
@@ -176,10 +183,13 @@ mod prim_bool { }
176183
///
177184
/// Since `!` has no values, it has no default value either. It's true that we could write an
178185
/// `impl` for this which simply panics, but the same is true for any type (we could `impl
179-
/// Default` for (eg.) `File` by just making `default()` panic.)
186+
/// Default` for (eg.) [`File`] by just making [`default()`] panic.)
180187
///
188+
/// [`fmt::Result`]: fmt/type.Result.html
189+
/// [`File`]: fs/struct.File.html
181190
/// [`Debug`]: fmt/trait.Debug.html
182191
/// [`Default`]: default/trait.Default.html
192+
/// [`default()`]: default/trait.Default.html#tymethod.default
183193
///
184194
#[unstable(feature = "never_type_impls", issue = "35121")]
185195
mod prim_never { }

0 commit comments

Comments
 (0)