From 9307917d6abc115faf7d2cb625c550cb509b5c4d Mon Sep 17 00:00:00 2001 From: Jonathan Strong Date: Wed, 6 Dec 2017 20:30:57 -0500 Subject: [PATCH 1/2] Adds language to the documentation for `Option` and `Result` suggesting the use of lazily evaluated alternatives when appropriate. These comments are intended to echo a clippy lint on the same topic (see https://rust-lang-nursery.github.io/rust-clippy/master/index.html#or_fun_call) --- src/libcore/option.rs | 12 ++++++++++++ src/libcore/result.rs | 8 ++++++++ 2 files changed, 20 insertions(+) diff --git a/src/libcore/option.rs b/src/libcore/option.rs index 980ea551f0806..e354c7e16a13c 100644 --- a/src/libcore/option.rs +++ b/src/libcore/option.rs @@ -338,6 +338,10 @@ impl Option { /// Returns the contained value or a default. /// + /// Arguments passed to `unwrap_or` are eagerly evaluated; if you are passing + /// the result of a function call, it is recommended to use `unwrap_or_else`, + /// which is lazily evaluated. + /// /// # Examples /// /// ``` @@ -451,6 +455,10 @@ impl Option { /// Transforms the `Option` into a [`Result`], mapping [`Some(v)`] to /// [`Ok(v)`] and [`None`] to [`Err(err)`]. /// + /// Arguments passed to `ok_or` are eagerly evaluated; if you are passing the + /// result of a function call, it is recommended to use `ok_or_else`, which is + /// lazily evaluated. + /// /// [`Result`]: ../../std/result/enum.Result.html /// [`Ok(v)`]: ../../std/result/enum.Result.html#variant.Ok /// [`Err(err)`]: ../../std/result/enum.Result.html#variant.Err @@ -609,6 +617,10 @@ impl Option { /// Returns the option if it contains a value, otherwise returns `optb`. /// + /// Arguments passed to `or` are eagerly evaluated; if you are passing the + /// result of a function call, it is recommended to use `or_else`, which is + /// lazily evaluated. + /// /// # Examples /// /// ``` diff --git a/src/libcore/result.rs b/src/libcore/result.rs index db5bffced10cc..438b3ed46a145 100644 --- a/src/libcore/result.rs +++ b/src/libcore/result.rs @@ -625,6 +625,10 @@ impl Result { /// Returns `res` if the result is [`Err`], otherwise returns the [`Ok`] value of `self`. /// + /// Arguments passed to `or` are eagerly evaluated; if you are passing the + /// result of a function call, it is recommended to use `or_else`, which is + /// lazily evaluated. + /// /// [`Ok`]: enum.Result.html#variant.Ok /// [`Err`]: enum.Result.html#variant.Err /// @@ -690,6 +694,10 @@ impl Result { /// Unwraps a result, yielding the content of an [`Ok`]. /// Else, it returns `optb`. /// + /// Arguments passed to `unwrap_or` are eagerly evaluated; if you are passing + /// the result of a function call, it is recommended to use `unwrap_or_else`, + /// which is lazily evaluated. + /// /// [`Ok`]: enum.Result.html#variant.Ok /// [`Err`]: enum.Result.html#variant.Err /// From 5847d0babdb4bc4545d9aeb9ef89862589ae1504 Mon Sep 17 00:00:00 2001 From: Jonathan Strong Date: Thu, 7 Dec 2017 12:19:24 -0500 Subject: [PATCH 2/2] adds links to methods, removes trailing whitespace --- src/libcore/option.rs | 15 ++++++++++----- src/libcore/result.rs | 10 ++++++---- 2 files changed, 16 insertions(+), 9 deletions(-) diff --git a/src/libcore/option.rs b/src/libcore/option.rs index e354c7e16a13c..0d7ec6071fbad 100644 --- a/src/libcore/option.rs +++ b/src/libcore/option.rs @@ -338,9 +338,11 @@ impl Option { /// Returns the contained value or a default. /// - /// Arguments passed to `unwrap_or` are eagerly evaluated; if you are passing - /// the result of a function call, it is recommended to use `unwrap_or_else`, - /// which is lazily evaluated. + /// Arguments passed to `unwrap_or` are eagerly evaluated; if you are passing + /// the result of a function call, it is recommended to use [`unwrap_or_else`], + /// which is lazily evaluated. + /// + /// [`unwrap_or_else`]: #method.unwrap_or_else /// /// # Examples /// @@ -456,7 +458,7 @@ impl Option { /// [`Ok(v)`] and [`None`] to [`Err(err)`]. /// /// Arguments passed to `ok_or` are eagerly evaluated; if you are passing the - /// result of a function call, it is recommended to use `ok_or_else`, which is + /// result of a function call, it is recommended to use [`ok_or_else`], which is /// lazily evaluated. /// /// [`Result`]: ../../std/result/enum.Result.html @@ -464,6 +466,7 @@ impl Option { /// [`Err(err)`]: ../../std/result/enum.Result.html#variant.Err /// [`None`]: #variant.None /// [`Some(v)`]: #variant.Some + /// [`ok_or_else`]: #method.ok_or_else /// /// # Examples /// @@ -618,9 +621,11 @@ impl Option { /// Returns the option if it contains a value, otherwise returns `optb`. /// /// Arguments passed to `or` are eagerly evaluated; if you are passing the - /// result of a function call, it is recommended to use `or_else`, which is + /// result of a function call, it is recommended to use [`or_else`], which is /// lazily evaluated. /// + /// [`or_else`]: #method.or_else + /// /// # Examples /// /// ``` diff --git a/src/libcore/result.rs b/src/libcore/result.rs index 438b3ed46a145..97cfc2b4dbc53 100644 --- a/src/libcore/result.rs +++ b/src/libcore/result.rs @@ -626,11 +626,12 @@ impl Result { /// Returns `res` if the result is [`Err`], otherwise returns the [`Ok`] value of `self`. /// /// Arguments passed to `or` are eagerly evaluated; if you are passing the - /// result of a function call, it is recommended to use `or_else`, which is + /// result of a function call, it is recommended to use [`or_else`], which is /// lazily evaluated. /// /// [`Ok`]: enum.Result.html#variant.Ok /// [`Err`]: enum.Result.html#variant.Err + /// [`or_else`]: #method.or_else /// /// # Examples /// @@ -694,12 +695,13 @@ impl Result { /// Unwraps a result, yielding the content of an [`Ok`]. /// Else, it returns `optb`. /// - /// Arguments passed to `unwrap_or` are eagerly evaluated; if you are passing - /// the result of a function call, it is recommended to use `unwrap_or_else`, - /// which is lazily evaluated. + /// Arguments passed to `unwrap_or` are eagerly evaluated; if you are passing + /// the result of a function call, it is recommended to use [`unwrap_or_else`], + /// which is lazily evaluated. /// /// [`Ok`]: enum.Result.html#variant.Ok /// [`Err`]: enum.Result.html#variant.Err + /// [`unwrap_or_else`]: #method.unwrap_or_else /// /// # Examples ///