---

yaml
---
r: 174701
b: refs/heads/snap-stage3
c: 39676c8
h: refs/heads/master
i:
  174699: 943844e
v: v3

Author: sellibitze

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: a0f86de49748b472d4d189d9688b0d856c000914
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: 5eb254b1ccf196ea0856782eba96f92ae0786617
+refs/heads/snap-stage3: 39676c8bf0ad0fe7249f788ab6ab6790360af73c
 refs/heads/try: 08f6380a9f0b866796080094f44fe25ea5636547
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/dist-snap: ba4081a5a8573875fed17545846f6f6902c8ba8d

branches/snap-stage3/src/libcore/ops.rs

@@ -13,12 +13,20 @@
 //! Implementing these traits allows you to get an effect similar to
 //! overloading operators.
 //!
-//! The values for the right hand side of an operator are automatically
-//! borrowed, so `a + b` is sugar for `a.add(&b)`.
-//!
-//! All of these traits are imported by the prelude, so they are available in
+//! Some of these traits are imported by the prelude, so they are available in
 //! every Rust program.
 //!
+//! Many of the operators take their operands by value. In non-generic
+//! contexts involving built-in types, this is usually not a problem.
+//! However, using these operators in generic code, requires some
+//! attention if values have to be reused as opposed to letting the operators
+//! consume them. One option is to occasionally use `clone()`.
+//! Another option is to rely on the types involved providing additional
+//! operator implementations for references. For example, for a user-defined
+//! type `T` which is supposed to support addition, it is probably a good
+//! idea to have both `T` and `&T` implement the traits `Add<T>` and `Add<&T>`
+//! so that generic code can be written without unnecessary cloning.
+//!
 //! # Example
 //!
 //! This example creates a `Point` struct that implements `Add` and `Sub`, and then