From 9307917d6abc115faf7d2cb625c550cb509b5c4d Mon Sep 17 00:00:00 2001
From: Jonathan Strong <jstrong@legis.io>
Date: Wed, 6 Dec 2017 20:30:57 -0500
Subject: [PATCH] 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<T> Option<T> {
 
     /// 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<T> Option<T> {
     /// Transforms the `Option<T>` into a [`Result<T, E>`], 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<T, E>`]: ../../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<T> Option<T> {
 
     /// 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<T, E> Result<T, E> {
 
     /// 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<T, E> Result<T, E> {
     /// 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
     ///