-
Notifications
You must be signed in to change notification settings - Fork 13.2k
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
bors
merged 21 commits into
rust-lang:master
from
carols10cents:trait-documentation-clarifications
May 27, 2016
Merged
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 bbfb6e7
`derive` explanation for PartialOrd should match that for Ord
carols10cents 2f44053
Make `Derivable` header be an h2 instead of an h1
carols10cents fc467b3
Reorder `Copy` doc sections
carols10cents e831c72
Add an explicit "How can I implement `PartialEq`"? doc section
carols10cents 54d2ef0
Add an explicit "How can I implement `Eq`" doc section
carols10cents c41227f
Add more detail to `Clone`'s documentation
carols10cents 61bb9b2
Add more information about implementing `Hash`
carols10cents 9efa445
Add an explicit "How can I implement `Ord`" doc section
carols10cents 8b00a08
Add an explicit "How can I implement `PartialOrd`" doc section
carols10cents bd50eff
Make the Default docs more like the other traits
carols10cents b4e123d
Shorten, yet clarify, initial summary sentences
carols10cents d2ee6e0
Emphasize semantic differences of Copy/Clone rather than impl
carols10cents c22c524
"more than 32" => "more than 32 elements"
carols10cents 497cbb6
"non equal" => "not equal"; consistent with the surrounding text
carols10cents 9149992
Add some newlines in some code examples
carols10cents daa9dca
Use `()` when referring to functions
carols10cents d81a999
Prefer `ClassName` over `Self` in example trait implementations
carols10cents 1b32298
Move all `Default` docs from module to trait
carols10cents 1a7d3e1
Complete `PartialOrd`'s example so it passes make check-docs
carols10cents 1e809f5
"the trait `Hash`" => "the `Hash` trait"
carols10cents File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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, | ||
/// } | ||
/// | ||
/// 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 | ||
/// | ||
|
@@ -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 | ||
|
@@ -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; | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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`. | ||
|
@@ -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 | ||
/// | ||
|
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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