Add explanations about what derived trait implementations do

5 files changed, 19 insertions, 6 deletions

diff --git a/src/libcore/clone.rs b/src/libcore/clone.rs
index e8ea993c694..cfb29cf479d 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 d3481ba3f05..cd0bbcd3356 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 dde4d03dad8..6579e5dab54 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 4d0fed98334..7f0d7517a57 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 1ed2a219fac..e519071a56e 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 {