From a2e79a7e525ca85d9e8b60569d4ffeeb999b03b8 Mon Sep 17 00:00:00 2001 From: Andrew Cann Date: Tue, 28 Nov 2017 23:20:43 +0800 Subject: Add more links to `!` doc text --- src/libstd/primitive_docs.rs | 46 +++++++++++++++++++++++++++----------------- 1 file changed, 28 insertions(+), 18 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/primitive_docs.rs b/src/libstd/primitive_docs.rs index 7c3d9fd8024..b24f4d12ebb 100644 --- a/src/libstd/primitive_docs.rs +++ b/src/libstd/primitive_docs.rs @@ -76,7 +76,7 @@ mod prim_bool { } /// so returns `!`. /// /// `break`, `continue` and `return` expressions also have type `!`. For example we are allowed to -/// write +/// write: /// /// ``` /// # #![feature(never_type)] @@ -104,10 +104,11 @@ mod prim_bool { } /// # } /// ``` /// -/// Both match arms must produce values of type `u32`, but since `break` never produces a value at -/// all we know it can never produce a value which isn't a `u32`. This illustrates another +/// Both match arms must produce values of type [`u32`], but since `break` never produces a value +/// at all we know it can never produce a value which isn't a [`u32`]. This illustrates another /// behaviour of the `!` type - expressions with type `!` will coerce into any other type. /// +/// [`u32`]: primitive.str.html /// [`exit`]: process/fn.exit.html /// /// # `!` and generics @@ -122,21 +123,27 @@ mod prim_bool { } /// } /// ``` /// -/// When implementing this trait for `String` we need to pick a type for `Err`. And since +/// When implementing this trait for [`String`] we need to pick a type for [`Err`]. And since /// converting a string into a string will never result in an error, the appropriate type is `!`. /// (Currently the type actually used is an enum with no variants, though this is only because `!` -/// was added to Rust at a later date and it may change in the future). With an `Err` type of `!`, -/// if we have to call `String::from_str` for some reason the result will be a `Result` -/// which we can unpack like this: +/// was added to Rust at a later date and it may change in the future). With an [`Err`] type of +/// `!`, if we have to call [`String::from_str`] for some reason the result will be a +/// [`Result`] which we can unpack like this: /// /// ```ignore (string-from-str-error-type-is-not-never-yet) /// let Ok(s) = String::from_str("hello"); /// ``` /// -/// Since the `Err` variant contains a `!`, it can never occur. So we can exhaustively match on -/// `Result` by just taking the `Ok` variant. This illustrates another behaviour of `!` - it -/// can be used to "delete" certain enum variants from generic types like `Result`. +/// Since the [`Err`] variant contains a `!`, it can never occur. So we can exhaustively match on +/// [`Result`] by just taking the [`Ok`] variant. This illustrates another behaviour of `!` - +/// it can be used to "delete" certain enum variants from generic types like `Result`. /// +/// [`String::from_str`]: str/trait.FromStr.html#tymethod.from_str +/// [`Result`]: result/enum.Result.html +/// [`Result`]: result/enum.Result.html +/// [`Ok`]: result/enum.Result.html#variant.Ok +/// [`String`]: string/struct.String.html +/// [`Err`]: result/enum.Result.html#variant.Err /// [`FromStr`]: str/trait.FromStr.html /// /// # `!` and traits @@ -158,13 +165,13 @@ mod prim_bool { } /// } /// ``` /// -/// Once again we're using `!`'s ability to coerce into any other type, in this case `fmt::Result`. -/// Since this method takes a `&!` as an argument we know that it can never be called (because -/// there is no value of type `!` for it to be called with). Writing `*self` essentially tells the -/// compiler "We know that this code can never be run, so just treat the entire function body has -/// having type `fmt::Result`". This pattern can be used a lot when implementing traits for `!`. -/// Generally, any trait which only has methods which take a `self` parameter should have such as -/// impl. +/// Once again we're using `!`'s ability to coerce into any other type, in this case +/// [`fmt::Result`]. Since this method takes a `&!` as an argument we know that it can never be +/// called (because there is no value of type `!` for it to be called with). Writing `*self` +/// essentially tells the compiler "We know that this code can never be run, so just treat the +/// entire function body has having type [`fmt::Result`]". This pattern can be used a lot when +/// implementing traits for `!`. Generally, any trait which only has methods which take a `self` +/// parameter should have such as impl. /// /// On the other hand, one trait which would not be appropriate to implement is [`Default`]: /// @@ -176,10 +183,13 @@ mod prim_bool { } /// /// Since `!` has no values, it has no default value either. It's true that we could write an /// `impl` for this which simply panics, but the same is true for any type (we could `impl -/// Default` for (eg.) `File` by just making `default()` panic.) +/// Default` for (eg.) [`File`] by just making [`default()`] panic.) /// +/// [`fmt::Result`]: fmt/type.Result.html +/// [`File`]: fs/struct.File.html /// [`Debug`]: fmt/trait.Debug.html /// [`Default`]: default/trait.Default.html +/// [`default()`]: default/trait.Default.html#tymethod.default /// #[unstable(feature = "never_type_impls", issue = "35121")] mod prim_never { } -- cgit 1.4.1-3-g733a5