From e36c7da56c74368881b02a4bbf1f740714083c65 Mon Sep 17 00:00:00 2001 From: Dirk Gadsden Date: Sun, 6 Mar 2016 19:13:29 -0800 Subject: [PATCH 01/10] Clarify documentation of `hash::SipHasher` The docs were making assertions/recommendations they shouldn't have. This clarifies them and adds some helpful links. Fixes #32043. --- src/libcore/hash/sip.rs | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/src/libcore/hash/sip.rs b/src/libcore/hash/sip.rs index 722d77a8a11ef..b1aab4c693de5 100644 --- a/src/libcore/hash/sip.rs +++ b/src/libcore/hash/sip.rs @@ -19,15 +19,18 @@ use super::Hasher; /// /// See: http://131002.net/siphash/ /// -/// Consider this as a main "general-purpose" hash for all hashtables: it -/// runs at good speed (competitive with spooky and city) and permits -/// strong _keyed_ hashing. Key your hashtables from a strong RNG, -/// such as `rand::Rng`. +/// This is the default hashing function used by standard library (eg. +/// `collections::HashMap` uses it by default). +/// +/// SipHash is a general-purpose hashing function: it runs at a good +/// speed (competitive with Spooky and City) and permits strong _keyed_ +/// hashing. This lets you key your hashtables from a strong RNG, such +/// as [`rand::Rng`](https://doc.rust-lang.org/rand/rand/trait.Rng.html). /// /// Although the SipHash algorithm is considered to be cryptographically /// strong, this implementation has not been reviewed for such purposes. -/// As such, all cryptographic uses of this implementation are strongly -/// discouraged. +/// As such, all cryptographic uses of this implementation are _strongly +/// discouraged_. #[stable(feature = "rust1", since = "1.0.0")] pub struct SipHasher { k0: u64, From 054196d1d9b5e932e5a2dd69b77d9210e26b95b5 Mon Sep 17 00:00:00 2001 From: Dirk Gadsden Date: Sun, 6 Mar 2016 19:32:19 -0800 Subject: [PATCH 02/10] Amend `hash::SipHasher` docs to more strongly discourage cryptographic uses --- src/libcore/hash/sip.rs | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/libcore/hash/sip.rs b/src/libcore/hash/sip.rs index b1aab4c693de5..3a6686770f6e6 100644 --- a/src/libcore/hash/sip.rs +++ b/src/libcore/hash/sip.rs @@ -27,10 +27,9 @@ use super::Hasher; /// hashing. This lets you key your hashtables from a strong RNG, such /// as [`rand::Rng`](https://doc.rust-lang.org/rand/rand/trait.Rng.html). /// -/// Although the SipHash algorithm is considered to be cryptographically -/// strong, this implementation has not been reviewed for such purposes. -/// As such, all cryptographic uses of this implementation are _strongly -/// discouraged_. +/// Although the SipHash algorithm is considered to be generally strong, +/// it is not intended for cryptographic purposes. As such, all +/// cryptographic uses of this implementation are _strongly discouraged_. #[stable(feature = "rust1", since = "1.0.0")] pub struct SipHasher { k0: u64, From d7e406eab811ae5cbb01c986c6e9ff681e5a6657 Mon Sep 17 00:00:00 2001 From: Pyfisch Date: Tue, 8 Mar 2016 19:33:27 +0100 Subject: [PATCH 03/10] Remove final note from testing chapter. The information that documentation tests cannot be run in binary crates is already given at the beginning of the section. --- src/doc/book/testing.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/doc/book/testing.md b/src/doc/book/testing.md index d57664bf07e4d..59d07e4f81c6e 100644 --- a/src/doc/book/testing.md +++ b/src/doc/book/testing.md @@ -515,7 +515,3 @@ you add more examples. We haven’t covered all of the details with writing documentation tests. For more, please see the [Documentation chapter](documentation.html). - -One final note: documentation tests *cannot* be run on binary crates. -To see more on file arrangement see the [Crates and -Modules](crates-and-modules.html) section. From 99eee832e035895e62d0ac52608e63199d80a35a Mon Sep 17 00:00:00 2001 From: Nathan Kleyn Date: Tue, 8 Mar 2016 22:53:54 +0000 Subject: [PATCH 04/10] Add missing documentation examples for BTreeSet. As part of the ongoing effort to document all methods with examples, this commit adds the missing examples for the `BTreeSet` collection type. This is part of issue #29348. --- src/libcollections/btree/set.rs | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/src/libcollections/btree/set.rs b/src/libcollections/btree/set.rs index 1cd50c2dcbe9e..dc653b446da45 100644 --- a/src/libcollections/btree/set.rs +++ b/src/libcollections/btree/set.rs @@ -38,6 +38,36 @@ use Bound; /// [`Ord`]: ../../core/cmp/trait.Ord.html /// [`Cell`]: ../../std/cell/struct.Cell.html /// [`RefCell`]: ../../std/cell/struct.RefCell.html +/// +/// # Examples +/// +/// ``` +/// use std::collections::BTreeSet; +/// +/// // Type inference lets us omit an explicit type signature (which +/// // would be `BTreeSet<&str>` in this example). +/// let mut books = BTreeSet::new(); +/// +/// // Add some books. +/// books.insert("A Dance With Dragons"); +/// books.insert("To Kill a Mockingbird"); +/// books.insert("The Odyssey"); +/// books.insert("The Great Gatsby"); +/// +/// // Check for a specific one. +/// if !books.contains("The Winds of Winter") { +/// println!("We have {} books, but The Winds of Winter ain't one.", +/// books.len()); +/// } +/// +/// // Remove a book. +/// books.remove("The Odyssey"); +/// +/// // Iterate over everything. +/// for book in &books { +/// println!("{}", book); +/// } +/// ``` #[derive(Clone, Hash, PartialEq, Eq, Ord, PartialOrd)] #[stable(feature = "rust1", since = "1.0.0")] pub struct BTreeSet { From 46dc35e4772e892bf1be04fa01767e0ec00ffe2f Mon Sep 17 00:00:00 2001 From: Dirk Gadsden Date: Tue, 8 Mar 2016 21:52:44 -0800 Subject: [PATCH 05/10] Link to actual CSPRNG in `hash::SipHasher` documentation --- src/libcore/hash/sip.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/libcore/hash/sip.rs b/src/libcore/hash/sip.rs index 3a6686770f6e6..342071f1b51b7 100644 --- a/src/libcore/hash/sip.rs +++ b/src/libcore/hash/sip.rs @@ -19,13 +19,13 @@ use super::Hasher; /// /// See: http://131002.net/siphash/ /// -/// This is the default hashing function used by standard library (eg. -/// `collections::HashMap` uses it by default). +/// This is currently the default hashing function used by standard library +/// (eg. `collections::HashMap` uses it by default). /// /// SipHash is a general-purpose hashing function: it runs at a good /// speed (competitive with Spooky and City) and permits strong _keyed_ -/// hashing. This lets you key your hashtables from a strong RNG, such -/// as [`rand::Rng`](https://doc.rust-lang.org/rand/rand/trait.Rng.html). +/// hashing. This lets you key your hashtables from a strong RNG, such as +/// [`rand::os::OsRng`](https://doc.rust-lang.org/rand/rand/os/struct.OsRng.html). /// /// Although the SipHash algorithm is considered to be generally strong, /// it is not intended for cryptographic purposes. As such, all From df550de689c27803c9b8d961c747e09cca36fd3e Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 9 Mar 2016 03:32:47 -0500 Subject: [PATCH 06/10] Clarify that try_unwrap needs exactly one Fixes #31950 --- src/liballoc/arc.rs | 5 +++-- src/liballoc/rc.rs | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/src/liballoc/arc.rs b/src/liballoc/arc.rs index 74325afaebd48..b5d7279edb006 100644 --- a/src/liballoc/arc.rs +++ b/src/liballoc/arc.rs @@ -201,11 +201,12 @@ impl Arc { Arc { _ptr: unsafe { Shared::new(Box::into_raw(x)) } } } - /// Unwraps the contained value if the `Arc` has only one strong reference. - /// This will succeed even if there are outstanding weak references. + /// Unwraps the contained value if the `Arc` has exactly one strong reference. /// /// Otherwise, an `Err` is returned with the same `Arc`. /// + /// This will succeed even if there are outstanding weak references. + /// /// # Examples /// /// ``` diff --git a/src/liballoc/rc.rs b/src/liballoc/rc.rs index 162312e2457da..dc283f5acdff8 100644 --- a/src/liballoc/rc.rs +++ b/src/liballoc/rc.rs @@ -224,11 +224,12 @@ impl Rc { } } - /// Unwraps the contained value if the `Rc` has only one strong reference. - /// This will succeed even if there are outstanding weak references. + /// Unwraps the contained value if the `Rc` has exactly one strong reference. /// /// Otherwise, an `Err` is returned with the same `Rc`. /// + /// This will succeed even if there are outstanding weak references. + /// /// # Examples /// /// ``` From 0f426aa916b17efab99cdc85a5b968d591b4cb4a Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 9 Mar 2016 03:37:19 -0500 Subject: [PATCH 07/10] Small grammar fix in Guessing Game When it was Option.expect(), there was an .ok().expect(), but now that it uses Result.expect(), there's only one method, not two. Fixes #31912 --- src/doc/book/guessing-game.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/guessing-game.md b/src/doc/book/guessing-game.md index b9b6e9a4c9568..e071bfdf8bce1 100644 --- a/src/doc/book/guessing-game.md +++ b/src/doc/book/guessing-game.md @@ -295,7 +295,7 @@ Rust warns us that we haven’t used the `Result` value. This warning comes from a special annotation that `io::Result` has. Rust is trying to tell you that you haven’t handled a possible error. The right way to suppress the error is to actually write error handling. Luckily, if we want to crash if there’s -a problem, we can use these two little methods. If we can recover from the +a problem, we can use `expect()`. If we can recover from the error somehow, we’d do something else, but we’ll save that for a future project. From aaca3175baab6fdd4f8895aa90f35318c87d7567 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 9 Mar 2016 03:42:36 -0500 Subject: [PATCH 08/10] Add other primitive types to the reference Fixes #31628 --- src/doc/reference.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/doc/reference.md b/src/doc/reference.md index 6fb8de780942c..c1f8d3d092a3c 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -3283,6 +3283,10 @@ The primitive types are the following: * The boolean type `bool` with values `true` and `false`. * The machine types (integer and floating-point). * The machine-dependent integer types. +* Arrays +* Tuples +* Slices +* Function pointers #### Machine types From 78484696fc6853a30c938c518e92a074ad94cc54 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 9 Mar 2016 03:52:35 -0500 Subject: [PATCH 09/10] Remove inaccurate claim about inline assembly It's not like GCC's. Fixes #20213 --- src/doc/book/inline-assembly.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/doc/book/inline-assembly.md b/src/doc/book/inline-assembly.md index 7659c4ff88dae..a5a2d7ce74e7d 100644 --- a/src/doc/book/inline-assembly.md +++ b/src/doc/book/inline-assembly.md @@ -2,8 +2,7 @@ For extremely low-level manipulations and performance reasons, one might wish to control the CPU directly. Rust supports using inline -assembly to do this via the `asm!` macro. The syntax roughly matches -that of GCC & Clang: +assembly to do this via the `asm!` macro. ```ignore asm!(assembly template From d9dba7699f6f9771f28438c2c49d920536d76a26 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Tue, 23 Feb 2016 00:04:30 -0500 Subject: [PATCH 10/10] Prefer 'associated function' over 'static method' in msg. TRPL seems to refer to 'static functions' as 'associated functions'. This terminology should be used consistently. --- src/librustc_typeck/check/method/suggest.rs | 3 ++- src/test/compile-fail/issue-7575.rs | 7 ++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/src/librustc_typeck/check/method/suggest.rs b/src/librustc_typeck/check/method/suggest.rs index 1367db16314e2..8ac002bc4dffd 100644 --- a/src/librustc_typeck/check/method/suggest.rs +++ b/src/librustc_typeck/check/method/suggest.rs @@ -141,7 +141,8 @@ pub fn report_error<'a, 'tcx>(fcx: &FnCtxt<'a, 'tcx>, if !static_sources.is_empty() { err.fileline_note( span, - "found defined static methods, maybe a `self` is missing?"); + "found the following associated functions; to be used as \ + methods, functions must have a `self` parameter"); report_candidates(fcx, &mut err, span, item_name, static_sources); } diff --git a/src/test/compile-fail/issue-7575.rs b/src/test/compile-fail/issue-7575.rs index 6c7196527efdb..3cb30981b673c 100644 --- a/src/test/compile-fail/issue-7575.rs +++ b/src/test/compile-fail/issue-7575.rs @@ -9,6 +9,7 @@ // except according to those terms. // Test the mechanism for warning about possible missing `self` declarations. +// ignore-tidy-linelength trait CtxtFn { fn f8(self, usize) -> usize; @@ -72,15 +73,15 @@ impl ManyImplTrait for Myisize {} fn no_param_bound(u: usize, m: Myisize) -> usize { u.f8(42) + u.f9(342) + m.fff(42) //~^ ERROR no method named `f9` found for type `usize` in the current scope - //~^^ NOTE found defined static methods, maybe a `self` is missing? + //~^^ NOTE found the following associated functions; to be used as methods, functions must have a `self` parameter //~^^^ ERROR no method named `fff` found for type `Myisize` in the current scope - //~^^^^ NOTE found defined static methods, maybe a `self` is missing? + //~^^^^ NOTE found the following associated functions; to be used as methods, functions must have a `self` parameter } fn param_bound(t: T) -> bool { t.is_str() //~^ ERROR no method named `is_str` found for type `T` in the current scope - //~^^ NOTE found defined static methods, maybe a `self` is missing? + //~^^ NOTE found the following associated functions; to be used as methods, functions must have a `self` parameter } fn main() {