From 1e493fd979c826c44b2fa5d4b74302d405fbd17d Mon Sep 17 00:00:00 2001
From: "Carol (Nichols || Goulding)" <carol.nichols@gmail.com>
Date: Fri, 20 May 2016 15:50:34 -0400
Subject: [PATCH] Add explanations about what derived trait implementations do

---
 src/libcore/clone.rs    | 3 ++-
 src/libcore/cmp.rs      | 9 +++++++--
 src/libcore/fmt/mod.rs  | 6 +++++-
 src/libcore/hash/mod.rs | 4 +++-
 src/libcore/marker.rs   | 3 ++-
 5 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/src/libcore/clone.rs b/src/libcore/clone.rs
index e8ea993c6940..cfb29cf479d8 100644
--- a/src/libcore/clone.rs
+++ b/src/libcore/clone.rs
@@ -48,7 +48,8 @@ use marker::Sized;
 
 /// A common trait for cloning an object.
 ///
-/// This trait can be used with `#[derive]`.
+/// This trait can be used with `#[derive]` if all fields are `Clone`. The `derive`d
+/// implementation of `clone()` calls `clone()` on each field.
 ///
 /// Types that are `Copy` should have a trivial implementation of `Clone`. More formally:
 /// if `T: Copy`, `x: T`, and `y: &T`, then `let x = y.clone();` is equivalent to `let x = *y;`.
diff --git a/src/libcore/cmp.rs b/src/libcore/cmp.rs
index d3481ba3f052..cd0bbcd33569 100644
--- a/src/libcore/cmp.rs
+++ b/src/libcore/cmp.rs
@@ -58,7 +58,10 @@ use option::Option::{self, Some};
 /// the rule that `eq` is a strict inverse of `ne`; that is, `!(a == b)` if and
 /// only if `a != b`.
 ///
-/// This trait can be used with `#[derive]`.
+/// This trait can be used with `#[derive]`. When `derive`d on structs, two
+/// instances are equal if all fields are equal, and non equal if any fields
+/// are not equal. When `derive`d on enums, each variant is equal to itself
+/// and not equal to the other variants.
 ///
 /// # Examples
 ///
@@ -96,7 +99,9 @@ pub trait PartialEq<Rhs: ?Sized = Self> {
 /// This property cannot be checked by the compiler, and therefore `Eq` implies
 /// `PartialEq`, and has no extra methods.
 ///
-/// This trait can be used with `#[derive]`.
+/// This trait can be used with `#[derive]`. When `derive`d, because `Eq` has
+/// no extra methods, it is only informing the compiler that this is an
+/// equivalence relation rather than a partial equivalence relation.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Eq: PartialEq<Self> {
     // FIXME #13101: this method is used solely by #[deriving] to
diff --git a/src/libcore/fmt/mod.rs b/src/libcore/fmt/mod.rs
index dde4d03dad8a..6579e5dab543 100644
--- a/src/libcore/fmt/mod.rs
+++ b/src/libcore/fmt/mod.rs
@@ -318,7 +318,11 @@ impl<'a> Display for Arguments<'a> {
 ///
 /// [module]: ../../std/fmt/index.html
 ///
-/// This trait can be used with `#[derive]`.
+/// This trait can be used with `#[derive]` if all fields implement `Debug`. When
+/// `derive`d for structs, it will use the name of the `struct`, then `{`, then a
+/// comma-separated list of each field's name and `Debug` value, then `}`. For
+/// `enum`s, it will use the name of the variant and, if applicable, `(`, then the
+/// `Debug` values of the fields, then `)`.
 ///
 /// # Examples
 ///
diff --git a/src/libcore/hash/mod.rs b/src/libcore/hash/mod.rs
index 4d0fed983343..7f0d7517a57c 100644
--- a/src/libcore/hash/mod.rs
+++ b/src/libcore/hash/mod.rs
@@ -97,7 +97,9 @@ mod sip;
 /// In other words, if two keys are equal, their hashes should also be equal.
 /// `HashMap` and `HashSet` both rely on this behavior.
 ///
-/// This trait can be used with `#[derive]`.
+/// This trait can be used with `#[derive]` if all fields implement `Hash`.
+/// When `derive`d, the resulting hash will be the combination of the values
+/// from calling `.hash()` on each field.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Hash {
     /// Feeds this value into the state given, updating the hasher as necessary.
diff --git a/src/libcore/marker.rs b/src/libcore/marker.rs
index 1ed2a219fac3..e519071a56ee 100644
--- a/src/libcore/marker.rs
+++ b/src/libcore/marker.rs
@@ -173,7 +173,8 @@ pub trait Unsize<T: ?Sized> {
 ///
 /// # Derivable
 ///
-/// This trait can be used with `#[derive]`.
+/// This trait can be used with `#[derive]` if all of its components implement `Copy` and the type
+/// implements `Clone`. The implementation will copy the bytes of each field using `memcpy`.
 #[stable(feature = "rust1", since = "1.0.0")]
 #[lang = "copy"]
 pub trait Copy : Clone {