2 files changed, 16 insertions, 10 deletions
diff --git a/library/alloc/src/rc.rs b/library/alloc/src/rc.rs
index eaf67cfda25..6dcd0c6056c 100644
--- a/library/alloc/src/rc.rs
+++ b/library/alloc/src/rc.rs
@@ -44,15 +44,18 @@
 //! Rc::downgrade(&my_rc);
 //! ```
 //!
-//! `Rc<T>`'s implementations of traits like `Clone` should also be called using
-//! fully qualified syntax to avoid confusion as to whether the *reference* is being
-//! cloned or the *backing data* (`T`) is being cloned:
+//! `Rc<T>`'s implementations of traits like `Clone` may also be called using
+//! fully qualified syntax. Some people prefer to use fully qualified syntax,
+//! while others prefer using method-call syntax.
 //!
 //! ```
 //! use std::rc::Rc;
 //!
-//! let my_rc = Rc::new(());
-//! let your_rc = Rc::clone(&my_rc);
+//! let rc = Rc::new(());
+//! // Method-call syntax
+//! let rc2 = rc.clone();
+//! // Fully qualified syntax
+//! let rc3 = Rc::clone(&rc);
 //! ```
 //!
 //! [`Weak<T>`][`Weak`] does not auto-dereference to `T`, because the inner value may have
diff --git a/library/alloc/src/sync.rs b/library/alloc/src/sync.rs
index 5ec7d4e3c81..5ab930a5208 100644
--- a/library/alloc/src/sync.rs
+++ b/library/alloc/src/sync.rs
@@ -138,15 +138,18 @@ macro_rules! acquire {
 /// Arc::downgrade(&my_arc);
 /// ```
 ///
-/// `Arc<T>`'s implementations of traits like `Clone` should also be called using
-/// fully qualified syntax to avoid confusion as to whether the *reference* is being
-/// cloned or the *backing data* (`T`) is being cloned:
+/// `Arc<T>`'s implementations of traits like `Clone` may also be called using
+/// fully qualified syntax. Some people prefer to use fully qualified syntax,
+/// while others prefer using method-call syntax.
 ///
 /// ```
 /// use std::sync::Arc;
 ///
-/// let my_arc = Arc::new(());
-/// let your_arc = Arc::clone(&my_arc);
+/// let arc = Arc::new(());
+/// // Method-call syntax
+/// let arc2 = arc.clone();
+/// // Fully qualified syntax
+/// let arc3 = Arc::clone(&arc);
 /// ```
 ///
 /// [`Weak<T>`][Weak] does not auto-dereference to `T`, because the inner value may have