Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Trait documentation clarifications #33815

Merged
merged 21 commits into from
May 27, 2016
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
1e493fd
Add explanations about what derived trait implementations do
carols10cents May 20, 2016
bbfb6e7
`derive` explanation for PartialOrd should match that for Ord
carols10cents May 21, 2016
2f44053
Make `Derivable` header be an h2 instead of an h1
carols10cents May 21, 2016
fc467b3
Reorder `Copy` doc sections
carols10cents May 21, 2016
e831c72
Add an explicit "How can I implement `PartialEq`"? doc section
carols10cents May 21, 2016
54d2ef0
Add an explicit "How can I implement `Eq`" doc section
carols10cents May 21, 2016
c41227f
Add more detail to `Clone`'s documentation
carols10cents May 22, 2016
61bb9b2
Add more information about implementing `Hash`
carols10cents May 22, 2016
9efa445
Add an explicit "How can I implement `Ord`" doc section
carols10cents May 22, 2016
8b00a08
Add an explicit "How can I implement `PartialOrd`" doc section
carols10cents May 22, 2016
bd50eff
Make the Default docs more like the other traits
carols10cents May 22, 2016
b4e123d
Shorten, yet clarify, initial summary sentences
carols10cents May 23, 2016
d2ee6e0
Emphasize semantic differences of Copy/Clone rather than impl
carols10cents May 23, 2016
c22c524
"more than 32" => "more than 32 elements"
carols10cents May 23, 2016
497cbb6
"non equal" => "not equal"; consistent with the surrounding text
carols10cents May 23, 2016
9149992
Add some newlines in some code examples
carols10cents May 23, 2016
daa9dca
Use `()` when referring to functions
carols10cents May 23, 2016
d81a999
Prefer `ClassName` over `Self` in example trait implementations
carols10cents May 23, 2016
1b32298
Move all `Default` docs from module to trait
carols10cents May 23, 2016
1a7d3e1
Complete `PartialOrd`'s example so it passes make check-docs
carols10cents May 23, 2016
1e809f5
"the trait `Hash`" => "the `Hash` trait"
carols10cents May 23, 2016
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 30 additions & 2 deletions src/libcore/clone.rs
Original file line number Diff line number Diff line change
Expand Up @@ -46,14 +46,42 @@

use marker::Sized;

/// A common trait for cloning an object.
/// A common trait for the ability to explicitly duplicate an object.
///
/// This trait can be used with `#[derive]`.
/// Differs from `Copy` in that `Copy` is implicit and extremely inexpensive, while
/// `Clone` is always explicit and may or may not be expensive. In order to enforce
/// these characteristics, Rust does not allow you to reimplement `Copy`, but you
/// may reimplement `Clone` and run arbitrary code.
///
/// Since `Clone` is more general than `Copy`, you can automatically make anything
/// `Copy` be `Clone` as well.
///
/// ## Derivable
///
/// This trait can be used with `#[derive]` if all fields are `Clone`. The `derive`d
/// implementation of `clone()` calls `clone()` on each field.
///
/// ## How can I implement `Clone`?
///
/// 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;`.
/// Manual implementations should be careful to uphold this invariant; however, unsafe code
/// must not rely on it to ensure memory safety.
///
/// An example is an array holding more than 32 elements of a type that is `Clone`; the standard
/// library only implements `Clone` up until arrays of size 32. In this case, the implementation of
/// `Clone` cannot be `derive`d, but can be implemented as:
///
/// ```
/// #[derive(Copy)]
/// struct Stats {
/// frequencies: [i32; 100],
/// }
///
/// impl Clone for Stats {
/// fn clone(&self) -> Stats { *self }
/// }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub trait Clone : Sized {
/// Returns a copy of the value.
Expand Down
168 changes: 164 additions & 4 deletions src/libcore/cmp.rs
Original file line number Diff line number Diff line change
Expand Up @@ -53,12 +53,43 @@ use option::Option::{self, Some};
/// symmetrically and transitively: if `T: PartialEq<U>` and `U: PartialEq<V>`
/// then `U: PartialEq<T>` and `T: PartialEq<V>`.
///
/// ## Derivable
///
/// This trait can be used with `#[derive]`. When `derive`d on structs, two
/// instances are equal if all fields are equal, and not 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.
///
/// ## How can I implement `PartialEq`?
///
/// PartialEq only requires the `eq` method to be implemented; `ne` is defined
/// in terms of it by default. Any manual implementation of `ne` *must* respect
/// 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]`.
/// An example implementation for a domain in which two books are considered
/// the same book if their ISBN matches, even if the formats differ:
///
/// ```
/// enum BookFormat { Paperback, Hardback, Ebook }
/// struct Book {
/// isbn: i32,
/// format: BookFormat,
/// }
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: newline after this line, to give it some room

///
/// impl PartialEq for Book {
/// fn eq(&self, other: &Book) -> bool {
/// self.isbn == other.isbn
/// }
/// }
///
/// let b1 = Book { isbn: 3, format: BookFormat::Paperback };
/// let b2 = Book { isbn: 3, format: BookFormat::Ebook };
/// let b3 = Book { isbn: 10, format: BookFormat::Paperback };
///
/// assert!(b1 == b2);
/// assert!(b1 != b3);
/// ```
///
/// # Examples
///
Expand Down Expand Up @@ -96,7 +127,32 @@ 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]`.
/// ## Derivable
///
/// 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. Note that
/// the `derive` strategy requires all fields are `PartialEq`, which isn't
/// always desired.
///
/// ## How can I implement `Eq`?
///
/// If you cannot use the `derive` strategy, specify that your type implements
/// `Eq`, which has no methods:
///
/// ```
/// enum BookFormat { Paperback, Hardback, Ebook }
/// struct Book {
/// isbn: i32,
/// format: BookFormat,
/// }
/// impl PartialEq for Book {
/// fn eq(&self, other: &Book) -> bool {
/// self.isbn == other.isbn
/// }
/// }
/// impl Eq for Book {}
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub trait Eq: PartialEq<Self> {
// FIXME #13101: this method is used solely by #[deriving] to
Expand Down Expand Up @@ -190,8 +246,49 @@ impl Ordering {
/// - total and antisymmetric: exactly one of `a < b`, `a == b` or `a > b` is true; and
/// - transitive, `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`.
///
/// ## Derivable
///
/// This trait can be used with `#[derive]`. When `derive`d, it will produce a lexicographic
/// ordering based on the top-to-bottom declaration order of the struct's members.
///
/// ## How can I implement `Ord`?
///
/// `Ord` requires that the type also be `PartialOrd` and `Eq` (which requires `PartialEq`).
///
/// Then you must define an implementation for `cmp()`. You may find it useful to use
/// `cmp()` on your type's fields.
///
/// Here's an example where you want to sort people by height only, disregarding `id`
/// and `name`:
///
/// ```
/// use std::cmp::Ordering;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd add a newline after this

///
/// #[derive(Eq)]
/// struct Person {
/// id: u32,
/// name: String,
/// height: u32,
/// }
///
/// impl Ord for Person {
/// fn cmp(&self, other: &Person) -> Ordering {
/// self.height.cmp(&other.height)
/// }
/// }
///
/// impl PartialOrd for Person {
/// fn partial_cmp(&self, other: &Person) -> Option<Ordering> {
/// Some(self.cmp(other))
/// }
/// }
///
/// impl PartialEq for Person {
/// fn eq(&self, other: &Person) -> bool {
/// self.height == other.height
/// }
/// }
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub trait Ord: Eq + PartialOrd<Self> {
/// This method returns an `Ordering` between `self` and `other`.
Expand Down Expand Up @@ -242,15 +339,78 @@ impl PartialOrd for Ordering {
/// transitively: if `T: PartialOrd<U>` and `U: PartialOrd<V>` then `U: PartialOrd<T>` and `T:
/// PartialOrd<V>`.
///
/// ## Derivable
///
/// This trait can be used with `#[derive]`. When `derive`d, it will produce a lexicographic
/// ordering based on the top-to-bottom declaration order of the struct's members.
///
/// ## How can I implement `Ord`?
///
/// PartialOrd only requires implementation of the `partial_cmp` method, with the others generated
/// from default implementations.
///
/// However it remains possible to implement the others separately for types which do not have a
/// total order. For example, for floating point numbers, `NaN < 0 == false` and `NaN >= 0 ==
/// false` (cf. IEEE 754-2008 section 5.11).
///
/// This trait can be used with `#[derive]`. When `derive`d, it will produce an ordering
/// based on the top-to-bottom declaration order of the struct's members.
/// `PartialOrd` requires your type to be `PartialEq`.
///
/// If your type is `Ord`, you can implement `partial_cmp()` by using `cmp()`:
///
/// ```
/// use std::cmp::Ordering;
///
/// #[derive(Eq)]
/// struct Person {
/// id: u32,
/// name: String,
/// height: u32,
/// }
///
/// impl PartialOrd for Person {
/// fn partial_cmp(&self, other: &Person) -> Option<Ordering> {
/// Some(self.cmp(other))
/// }
/// }
///
/// impl Ord for Person {
/// fn cmp(&self, other: &Person) -> Ordering {
/// self.height.cmp(&other.height)
/// }
/// }
///
/// impl PartialEq for Person {
/// fn eq(&self, other: &Person) -> bool {
/// self.height == other.height
/// }
/// }
/// ```
///
/// You may also find it useful to use `partial_cmp()` on your type`s fields. Here
/// is an example of `Person` types who have a floating-point `height` field that
/// is the only field to be used for sorting:
///
/// ```
/// use std::cmp::Ordering;
///
/// struct Person {
/// id: u32,
/// name: String,
/// height: f64,
/// }
///
/// impl PartialOrd for Person {
/// fn partial_cmp(&self, other: &Person) -> Option<Ordering> {
/// self.height.partial_cmp(&other.height)
/// }
/// }
///
/// impl PartialEq for Person {
/// fn eq(&self, other: &Person) -> bool {
/// self.height == other.height
/// }
/// }
/// ```
///
/// # Examples
///
Expand Down
Loading