From 6ba7065af18caa34a0da126488c64c46c0ca276c Mon Sep 17 00:00:00 2001 From: Oliver Schneider Date: Tue, 14 Feb 2017 14:48:26 +0100 Subject: [PATCH 01/16] enable tools to use test runners programmatically --- src/libtest/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libtest/lib.rs b/src/libtest/lib.rs index 112bf61cf9722..428365784a32f 100644 --- a/src/libtest/lib.rs +++ b/src/libtest/lib.rs @@ -950,7 +950,7 @@ fn stdout_isatty() -> bool { } #[derive(Clone)] -enum TestEvent { +pub enum TestEvent { TeFiltered(Vec), TeWait(TestDesc, NamePadding), TeResult(TestDesc, TestResult, Vec), @@ -960,7 +960,7 @@ enum TestEvent { pub type MonitorMsg = (TestDesc, TestResult, Vec); -fn run_tests(opts: &TestOpts, tests: Vec, mut callback: F) -> io::Result<()> +pub fn run_tests(opts: &TestOpts, tests: Vec, mut callback: F) -> io::Result<()> where F: FnMut(TestEvent) -> io::Result<()> { use std::collections::HashMap; From 80ac32330f35c5994d5d5f9e17bbe0dd9f1fdee3 Mon Sep 17 00:00:00 2001 From: Oliver Schneider Date: Tue, 14 Feb 2017 16:02:53 +0100 Subject: [PATCH 02/16] make more types public --- src/libtest/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libtest/lib.rs b/src/libtest/lib.rs index 428365784a32f..5fdb0aa0641a0 100644 --- a/src/libtest/lib.rs +++ b/src/libtest/lib.rs @@ -106,7 +106,7 @@ impl fmt::Display for TestName { } #[derive(Clone, Copy, PartialEq, Eq)] -enum NamePadding { +pub enum NamePadding { PadNone, PadOnRight, } From 5189c4f8c10d0b8cae1fb66e5b4e0717af30d60d Mon Sep 17 00:00:00 2001 From: Jakob Demler Date: Wed, 15 Feb 2017 12:59:01 +0100 Subject: [PATCH 03/16] custom attributes and error reporting docs for procedural macros --- src/doc/book/src/procedural-macros.md | 70 ++++++++++++++++++++++++++- 1 file changed, 69 insertions(+), 1 deletion(-) diff --git a/src/doc/book/src/procedural-macros.md b/src/doc/book/src/procedural-macros.md index d286c3b7bdc63..ef8b638dc1c60 100644 --- a/src/doc/book/src/procedural-macros.md +++ b/src/doc/book/src/procedural-macros.md @@ -209,5 +209,73 @@ Ok so now, let's compile `hello-world`. Executing `cargo run` now yields: Hello, World! My name is FrenchToast Hello, World! My name is Waffles ``` +## Custom Attributes +In some cases it might make sense to allow users some kind of configuration. +For our example the user might want to overwrite the name that is printed in the `hello_world()` method. -We've done it! +This can be achieved with custom attributes: +```rust,ignore +#[derive(HelloWorld)] +#[HelloWorldName = "the best Pancakes"] +struct Pancakes; + +fn main() { + Pancakes::hello_world(); +} +``` + +If we try to compile this though, the compiler will respond with an error: + +``` +error: The attribute `HelloWorldName` is currently unknown to the compiler and may have meaning added to it in the future (see issue #29642) +``` + +The compiler needs to know that we handle this attribute and to not respond with an error. +This is done in the `hello-world-derive`-crate by adding `attributes` to the `proc_macro_derive` attribute: + +```rust,ignore +#[proc_macro_derive(HelloWorld, attributes(HelloWorldName))] +pub fn hello_world(input: TokenStream) -> TokenStream +``` + +Multiple attributes can be specified that way. + + +## Raising Errors +Let's assume that we do not want to accept `Enums` as input to our custom derive method. + +This condition can be easily checked with the help of `syn`. +But how to we tell the user, that we do not accept `Enums`. +The idiomatic was to report errors in procedural macros is to panic: + +```rust,ignore +fn impl_hello_world(ast: &syn::MacroInput) -> quote::Tokens { + let name = &ast.ident; + // Check if derive(HelloWorld) was specified for a struct + if let syn::Body::Struct(_) = ast.body { + // Yes, this is a struct + quote! { + impl HelloWorld for #name { + fn hello_world() { + println!("Hello, World! My name is {}", stringify!(#name)); + } + } + } + } else { + //Nope. This is an Enum. We cannot handle these! + panic!("#[derive(HelloWorld)] is only defined for structs, not for enums!"); + } +} +``` + +If a user now tries to derive `HelloWorld` from an enum they will be greeted with following, hopefully helpful, error: + +``` +error: custom derive attribute panicked + --> src/main.rs + | + | #[derive(HelloWorld)] + | ^^^^^^^^^^ + | + = help: message: #[derive(HelloWorld)] is only defined for structs, not for enums! +``` From 9a39994ee3a6f825318af9d6ceb23ee3187c7888 Mon Sep 17 00:00:00 2001 From: Jakob Demler Date: Wed, 15 Feb 2017 15:31:52 +0100 Subject: [PATCH 04/16] add bash to error-messages --- src/doc/book/src/procedural-macros.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/book/src/procedural-macros.md b/src/doc/book/src/procedural-macros.md index ef8b638dc1c60..e9777f9992f74 100644 --- a/src/doc/book/src/procedural-macros.md +++ b/src/doc/book/src/procedural-macros.md @@ -226,7 +226,7 @@ fn main() { If we try to compile this though, the compiler will respond with an error: -``` +```bash error: The attribute `HelloWorldName` is currently unknown to the compiler and may have meaning added to it in the future (see issue #29642) ``` @@ -270,7 +270,7 @@ fn impl_hello_world(ast: &syn::MacroInput) -> quote::Tokens { If a user now tries to derive `HelloWorld` from an enum they will be greeted with following, hopefully helpful, error: -``` +```bash error: custom derive attribute panicked --> src/main.rs | From 8685adb26b0ec6a0b4fad2cb7765fae3b9f2e25c Mon Sep 17 00:00:00 2001 From: Michal Nazarewicz Date: Mon, 13 Feb 2017 03:00:06 +0100 Subject: [PATCH 05/16] book: binary prefixed are defined by IEC and not in SI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Binary prefixes (such as Gi for ‘gibi-’ in GiB) are defined by International Electrotechnical Commission (IEC) and not in the International System of Units (SI). --- src/doc/book/src/the-stack-and-the-heap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/src/the-stack-and-the-heap.md b/src/doc/book/src/the-stack-and-the-heap.md index b9b3b801eae58..6866505df1310 100644 --- a/src/doc/book/src/the-stack-and-the-heap.md +++ b/src/doc/book/src/the-stack-and-the-heap.md @@ -86,7 +86,7 @@ to a large number, representing how much RAM your computer has. For example, if you have a gigabyte of RAM, your addresses go from `0` to `1,073,741,823`. That number comes from 230, the number of bytes in a gigabyte. [^gigabyte] -[^gigabyte]: ‘Gigabyte’ can mean two things: 10^9, or 2^30. The SI standard resolved this by stating that ‘gigabyte’ is 10^9, and ‘gibibyte’ is 2^30. However, very few people use this terminology, and rely on context to differentiate. We follow in that tradition here. +[^gigabyte]: ‘Gigabyte’ can mean two things: 109, or 230. The IEC standard resolved this by stating that ‘gigabyte’ is 109, and ‘gibibyte’ is 230. However, very few people use this terminology, and rely on context to differentiate. We follow in that tradition here. This memory is kind of like a giant array: addresses start at zero and go up to the final number. So here’s a diagram of our first stack frame: From 97451996e69a0bb8d98cfe77bd904d8033419ab9 Mon Sep 17 00:00:00 2001 From: Jakob Demler Date: Wed, 15 Feb 2017 21:21:31 +0100 Subject: [PATCH 06/16] fixed whitespace issues --- src/doc/book/src/procedural-macros.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/doc/book/src/procedural-macros.md b/src/doc/book/src/procedural-macros.md index e9777f9992f74..468a8f904a45a 100644 --- a/src/doc/book/src/procedural-macros.md +++ b/src/doc/book/src/procedural-macros.md @@ -209,7 +209,9 @@ Ok so now, let's compile `hello-world`. Executing `cargo run` now yields: Hello, World! My name is FrenchToast Hello, World! My name is Waffles ``` + ## Custom Attributes + In some cases it might make sense to allow users some kind of configuration. For our example the user might want to overwrite the name that is printed in the `hello_world()` method. @@ -240,8 +242,8 @@ pub fn hello_world(input: TokenStream) -> TokenStream Multiple attributes can be specified that way. - ## Raising Errors + Let's assume that we do not want to accept `Enums` as input to our custom derive method. This condition can be easily checked with the help of `syn`. From b2ac1c9c6b595f39c79e13bc4e0a0411441c7543 Mon Sep 17 00:00:00 2001 From: Matt Brubeck Date: Thu, 16 Feb 2017 09:18:18 -0800 Subject: [PATCH 07/16] Additional docs for Vec, String, and slice trait impls --- src/libcollections/string.rs | 42 ++++++++++++++++++++++++++++++++++++ src/libcollections/vec.rs | 2 ++ src/libcore/slice.rs | 2 ++ src/libcore/str/mod.rs | 14 ++++++++++++ 4 files changed, 60 insertions(+) diff --git a/src/libcollections/string.rs b/src/libcollections/string.rs index 4c82e2e2e7e35..a1e6c7fe6fe54 100644 --- a/src/libcollections/string.rs +++ b/src/libcollections/string.rs @@ -1629,6 +1629,43 @@ impl hash::Hash for String { } } +/// Implements the `+` operator for concatenating two strings. +/// +/// This consumes the `String` on the left-hand side and re-uses its buffer (growing it if +/// necessary). This is done to avoid allocating a new `String` and copying the entire contents on +/// every operation, which would lead to `O(n^2)` running time when building an `n`-byte string by +/// repeated concatenation. +/// +/// The string on the right-hand side is only borrowed; its contents are copied into the returned +/// `String`. +/// +/// # Examples +/// +/// Concatenating two `String`s takes the first by value and borrows the second: +/// +/// ``` +/// let a = String::from("hello"); +/// let b = String::from(" world"); +/// let c = a + &b; +/// // `a` is moved and can no longer be used here. +/// ``` +/// +/// If you want to keep using the first `String`, you can clone it and append to the clone instead: +/// +/// ``` +/// let a = String::from("hello"); +/// let b = String::from(" world"); +/// let c = a.clone() + &b; +/// // `a` is still valid here. +/// ``` +/// +/// Concatenating `&str` slices can be done by converting the first to a `String`: +/// +/// ``` +/// let a = "hello"; +/// let b = " world"; +/// let c = a.to_string() + b; +/// ``` #[stable(feature = "rust1", since = "1.0.0")] impl<'a> Add<&'a str> for String { type Output = String; @@ -1640,6 +1677,11 @@ impl<'a> Add<&'a str> for String { } } +/// Implements the `+=` operator for appending to a `String`. +/// +/// This has the same behavior as the [`push_str()`] method. +/// +/// [`push_str()`]: struct.String.html#method.push_str #[stable(feature = "stringaddassign", since = "1.12.0")] impl<'a> AddAssign<&'a str> for String { #[inline] diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs index 9e3f117f9b20e..bc7f562452d3b 100644 --- a/src/libcollections/vec.rs +++ b/src/libcollections/vec.rs @@ -1776,6 +1776,7 @@ array_impls! { 30 31 32 } +/// Implements comparison of vectors, lexicographically. #[stable(feature = "rust1", since = "1.0.0")] impl PartialOrd for Vec { #[inline] @@ -1787,6 +1788,7 @@ impl PartialOrd for Vec { #[stable(feature = "rust1", since = "1.0.0")] impl Eq for Vec {} +/// Implements ordering of vectors, lexicographically. #[stable(feature = "rust1", since = "1.0.0")] impl Ord for Vec { #[inline] diff --git a/src/libcore/slice.rs b/src/libcore/slice.rs index 3e0b842557353..0331c5d4ba401 100644 --- a/src/libcore/slice.rs +++ b/src/libcore/slice.rs @@ -2202,6 +2202,7 @@ impl PartialEq<[B]> for [A] where A: PartialEq { #[stable(feature = "rust1", since = "1.0.0")] impl Eq for [T] {} +/// Implements comparison of vectors lexicographically. #[stable(feature = "rust1", since = "1.0.0")] impl Ord for [T] { fn cmp(&self, other: &[T]) -> Ordering { @@ -2209,6 +2210,7 @@ impl Ord for [T] { } } +/// Implements comparison of vectors lexicographically. #[stable(feature = "rust1", since = "1.0.0")] impl PartialOrd for [T] { fn partial_cmp(&self, other: &[T]) -> Option { diff --git a/src/libcore/str/mod.rs b/src/libcore/str/mod.rs index 49a6b1b5fceb7..925cd84154a2e 100644 --- a/src/libcore/str/mod.rs +++ b/src/libcore/str/mod.rs @@ -1366,6 +1366,13 @@ mod traits { use ops; use str::eq_slice; + /// Implements ordering of strings. + /// + /// Strings are ordered lexicographically by their byte values. This orders Unicode code + /// points based on their positions in the code charts. This is not necessarily the same as + /// "alphabetical" order, which varies by language and locale. Sorting strings according to + /// culturally-accepted standards requires locale-specific data that is outside the scope of + /// the `str` type. #[stable(feature = "rust1", since = "1.0.0")] impl Ord for str { #[inline] @@ -1387,6 +1394,13 @@ mod traits { #[stable(feature = "rust1", since = "1.0.0")] impl Eq for str {} + /// Implements comparison operations on strings. + /// + /// Strings are compared lexicographically by their byte values. This compares Unicode code + /// points based on their positions in the code charts. This is not necessarily the same as + /// "alphabetical" order, which varies by language and locale. Comparing strings according to + /// culturally-accepted standards requires locale-specific data that is outside the scope of + /// the `str` type. #[stable(feature = "rust1", since = "1.0.0")] impl PartialOrd for str { #[inline] From ec648a1ab3b2f3523f2243ebf051cb39f4053902 Mon Sep 17 00:00:00 2001 From: Sean Griffin Date: Sat, 18 Feb 2017 16:39:55 -0500 Subject: [PATCH 08/16] Fix indentation of error message So I just encountered this error for the first time. It's unclear what it means, why I encountered it, or how to fix it. But worst of all, it has a random newline and weird indentation! This commit fixes that last bit. --- src/librustc/ty/inhabitedness/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/librustc/ty/inhabitedness/mod.rs b/src/librustc/ty/inhabitedness/mod.rs index 24ca476e5ff79..77c863a012318 100644 --- a/src/librustc/ty/inhabitedness/mod.rs +++ b/src/librustc/ty/inhabitedness/mod.rs @@ -187,7 +187,7 @@ impl<'a, 'gcx, 'tcx> TyS<'tcx> { // which contains a Foo<((T, T), (T, T))> // which contains a Foo<(((T, T), (T, T)), ((T, T), (T, T)))> // etc. - let error = format!("reached recursion limit while checking + let error = format!("reached recursion limit while checking \ inhabitedness of `{}`", self); tcx.sess.fatal(&error); } From 198208be0e818d99e42281568a2eec305175c6c9 Mon Sep 17 00:00:00 2001 From: Jakob Demler Date: Sun, 19 Feb 2017 18:15:44 +0100 Subject: [PATCH 09/16] Fixed some small issues --- src/doc/book/src/procedural-macros.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/src/doc/book/src/procedural-macros.md b/src/doc/book/src/procedural-macros.md index 468a8f904a45a..e22ef85546bdb 100644 --- a/src/doc/book/src/procedural-macros.md +++ b/src/doc/book/src/procedural-macros.md @@ -210,12 +210,15 @@ Hello, World! My name is FrenchToast Hello, World! My name is Waffles ``` +We've done it! + ## Custom Attributes In some cases it might make sense to allow users some kind of configuration. -For our example the user might want to overwrite the name that is printed in the `hello_world()` method. +For example, the user might want to overwrite the name that is printed in the `hello_world()` method. This can be achieved with custom attributes: + ```rust,ignore #[derive(HelloWorld)] #[HelloWorldName = "the best Pancakes"] @@ -232,8 +235,8 @@ If we try to compile this though, the compiler will respond with an error: error: The attribute `HelloWorldName` is currently unknown to the compiler and may have meaning added to it in the future (see issue #29642) ``` -The compiler needs to know that we handle this attribute and to not respond with an error. -This is done in the `hello-world-derive`-crate by adding `attributes` to the `proc_macro_derive` attribute: +The compiler needs to know that we're handling this attribute and to not respond with an error. +This is done in the `hello-world-derive` crate by adding `attributes` to the `proc_macro_derive` attribute: ```rust,ignore #[proc_macro_derive(HelloWorld, attributes(HelloWorldName))] @@ -244,11 +247,11 @@ Multiple attributes can be specified that way. ## Raising Errors -Let's assume that we do not want to accept `Enums` as input to our custom derive method. +Let's assume that we do not want to accept enums as input to our custom derive method. This condition can be easily checked with the help of `syn`. -But how to we tell the user, that we do not accept `Enums`. -The idiomatic was to report errors in procedural macros is to panic: +But how do we tell the user, that we do not accept enums? +The idiomatic way to report errors in procedural macros is to panic: ```rust,ignore fn impl_hello_world(ast: &syn::MacroInput) -> quote::Tokens { @@ -257,14 +260,14 @@ fn impl_hello_world(ast: &syn::MacroInput) -> quote::Tokens { if let syn::Body::Struct(_) = ast.body { // Yes, this is a struct quote! { - impl HelloWorld for #name { + impl HelloWorld for #name { fn hello_world() { println!("Hello, World! My name is {}", stringify!(#name)); } } } } else { - //Nope. This is an Enum. We cannot handle these! + //Nope. This is an Enum. We cannot handle these! panic!("#[derive(HelloWorld)] is only defined for structs, not for enums!"); } } From 58a9dd3f7e851193c732a8f850294d91906edb6b Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Tue, 21 Feb 2017 21:12:35 +0100 Subject: [PATCH 10/16] Add missing urls and examples into Barrier structs --- src/libstd/sync/barrier.rs | 76 ++++++++++++++++++++++++++++++++++---- 1 file changed, 69 insertions(+), 7 deletions(-) diff --git a/src/libstd/sync/barrier.rs b/src/libstd/sync/barrier.rs index fc4fd4ce92b1b..f15e7ff891684 100644 --- a/src/libstd/sync/barrier.rs +++ b/src/libstd/sync/barrier.rs @@ -14,6 +14,8 @@ use sync::{Mutex, Condvar}; /// A barrier enables multiple threads to synchronize the beginning /// of some computation. /// +/// # Examples +/// /// ``` /// use std::sync::{Arc, Barrier}; /// use std::thread; @@ -50,8 +52,19 @@ struct BarrierState { /// A result returned from wait. /// -/// Currently this opaque structure only has one method, `.is_leader()`. Only +/// Currently this opaque structure only has one method, [`.is_leader()`]. Only /// one thread will receive a result that will return `true` from this function. +/// +/// [`.is_leader()`]: #method.is_leader +/// +/// # Examples +/// +/// ``` +/// use std::sync::Barrier; +/// +/// let barrier = Barrier::new(1); +/// let barrier_wait_result = barrier.wait(); +/// ``` #[stable(feature = "rust1", since = "1.0.0")] pub struct BarrierWaitResult(bool); @@ -65,8 +78,18 @@ impl fmt::Debug for Barrier { impl Barrier { /// Creates a new barrier that can block a given number of threads. /// - /// A barrier will block `n`-1 threads which call `wait` and then wake up - /// all threads at once when the `n`th thread calls `wait`. + /// A barrier will block `n`-1 threads which call [`wait`] and then wake up + /// all threads at once when the `n`th thread calls [`wait`]. + /// + /// [`wait`]: #method.wait + /// + /// # Examples + /// + /// ``` + /// use std::sync::Barrier; + /// + /// let barrier = Barrier::new(10); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn new(n: usize) -> Barrier { Barrier { @@ -84,10 +107,37 @@ impl Barrier { /// Barriers are re-usable after all threads have rendezvoused once, and can /// be used continuously. /// - /// A single (arbitrary) thread will receive a `BarrierWaitResult` that - /// returns `true` from `is_leader` when returning from this function, and + /// A single (arbitrary) thread will receive a [`BarrierWaitResult`] that + /// returns `true` from [`is_leader`] when returning from this function, and /// all other threads will receive a result that will return `false` from - /// `is_leader` + /// [`is_leader`]. + /// + /// [`BarrierWaitResult`]: struct.BarrierWaitResult.html + /// [`is_leader`]: struct.BarrierWaitResult.html#method.is_leader + /// + /// # Examples + /// + /// ``` + /// use std::sync::{Arc, Barrier}; + /// use std::thread; + /// + /// let mut handles = Vec::with_capacity(10); + /// let barrier = Arc::new(Barrier::new(10)); + /// for _ in 0..10 { + /// let c = barrier.clone(); + /// // The same messages will be printed together. + /// // You will NOT see any interleaving. + /// handles.push(thread::spawn(move|| { + /// println!("before wait"); + /// c.wait(); + /// println!("after wait"); + /// })); + /// } + /// // Wait for other threads to finish. + /// for handle in handles { + /// handle.join().unwrap(); + /// } + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn wait(&self) -> BarrierWaitResult { let mut lock = self.lock.lock().unwrap(); @@ -120,10 +170,22 @@ impl fmt::Debug for BarrierWaitResult { } impl BarrierWaitResult { - /// Returns whether this thread from `wait` is the "leader thread". + /// Returns whether this thread from [`wait`] is the "leader thread". /// /// Only one thread will have `true` returned from their result, all other /// threads will have `false` returned. + /// + /// [`wait`]: struct.Barrier.html#method.wait + /// + /// # Examples + /// + /// ``` + /// use std::sync::Barrier; + /// + /// let barrier = Barrier::new(1); + /// let barrier_wait_result = barrier.wait(); + /// println!("{:?}", barrier_wait_result.is_leader()); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn is_leader(&self) -> bool { self.0 } } From 689dc26b685fb88993e055c4c2155b9a4b2c3797 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Wed, 22 Feb 2017 17:13:22 +0300 Subject: [PATCH 11/16] Clarify thread::Builder::stack_size --- src/libstd/thread/mod.rs | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs index 93e320c45223c..2bc066d3fea55 100644 --- a/src/libstd/thread/mod.rs +++ b/src/libstd/thread/mod.rs @@ -235,7 +235,7 @@ pub use self::local::{LocalKey, LocalKeyState}; pub struct Builder { // A name for the thread-to-be, for identification in panic messages name: Option, - // The size of the stack for the spawned thread + // The size of the stack for the spawned thread in bytes stack_size: Option, } @@ -289,14 +289,17 @@ impl Builder { self } - /// Sets the size of the stack for the new thread. + /// Sets the size of the stack (in bytes) for the new thread. + /// + /// The actual stack size may be greater than this value if + /// the platform specifies minimal stack size. /// /// # Examples /// /// ``` /// use std::thread; /// - /// let builder = thread::Builder::new().stack_size(10); + /// let builder = thread::Builder::new().stack_size(32 * 1024); /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn stack_size(mut self, size: usize) -> Builder { From 6b8e1756c7f3bf4d94973ef0702e252277d10763 Mon Sep 17 00:00:00 2001 From: Jim Blandy Date: Wed, 22 Feb 2017 21:18:52 -0800 Subject: [PATCH 12/16] Update std::fmt module docs for landing of #33642. --- src/libcollections/fmt.rs | 25 ++++--------------------- 1 file changed, 4 insertions(+), 21 deletions(-) diff --git a/src/libcollections/fmt.rs b/src/libcollections/fmt.rs index bd74848a01d83..079541235a25e 100644 --- a/src/libcollections/fmt.rs +++ b/src/libcollections/fmt.rs @@ -62,7 +62,7 @@ //! //! A format string is required to use all of its arguments, otherwise it is a //! compile-time error. You may refer to the same argument more than once in the -//! format string, although it must always be referred to with the same type. +//! format string. //! //! ## Named parameters //! @@ -89,19 +89,8 @@ //! //! ## Argument types //! -//! Each argument's type is dictated by the format string. It is a requirement -//! that every argument is only ever referred to by one type. For example, this -//! is an invalid format string: -//! -//! ```text -//! {0:x} {0:o} -//! ``` -//! -//! This is invalid because the first argument is both referred to as a -//! hexadecimal as well as an -//! octal. -//! -//! There are various parameters which do require a particular type, however. +//! Each argument's type is dictated by the format string. +//! There are various parameters which require a particular type, however. //! An example is the `{:.*}` syntax, which sets the number of decimal places //! in floating-point types: //! @@ -113,13 +102,7 @@ //! //! If this syntax is used, then the number of characters to print precedes the //! actual object being formatted, and the number of characters must have the -//! type `usize`. Although a `usize` can be printed with `{}`, it is invalid to -//! reference an argument as such. For example this is another invalid format -//! string: -//! -//! ```text -//! {:.*} {0} -//! ``` +//! type `usize`. //! //! ## Formatting traits //! From 84ca464f9c731b07a68cb264ecd37c9aacc2e475 Mon Sep 17 00:00:00 2001 From: Luxko Date: Thu, 23 Feb 2017 01:44:27 -0600 Subject: [PATCH 13/16] Update exception-safety.md Fix variable name typo --- src/doc/nomicon/src/exception-safety.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/nomicon/src/exception-safety.md b/src/doc/nomicon/src/exception-safety.md index 80e72cd5e36c9..0fb98a617688e 100644 --- a/src/doc/nomicon/src/exception-safety.md +++ b/src/doc/nomicon/src/exception-safety.md @@ -93,7 +93,7 @@ uselessly. We would rather have the following: ```text bubble_up(heap, index): let elem = heap[index] - while index != 0 && element < heap[parent(index)]: + while index != 0 && elem < heap[parent(index)]: heap[index] = heap[parent(index)] index = parent(index) heap[index] = elem From 729948f95853e0d7228e02dffca53539ddb0a9e0 Mon Sep 17 00:00:00 2001 From: Luxko Date: Thu, 23 Feb 2017 01:50:16 -0600 Subject: [PATCH 14/16] Update exception-safety.md --- src/doc/nomicon/src/exception-safety.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/nomicon/src/exception-safety.md b/src/doc/nomicon/src/exception-safety.md index 0fb98a617688e..a3cbc6abd69cc 100644 --- a/src/doc/nomicon/src/exception-safety.md +++ b/src/doc/nomicon/src/exception-safety.md @@ -137,7 +137,7 @@ If Rust had `try` and `finally` like in Java, we could do the following: bubble_up(heap, index): let elem = heap[index] try: - while index != 0 && element < heap[parent(index)]: +        while index != 0 && elem < heap[parent(index)]: heap[index] = heap[parent(index)] index = parent(index) finally: From 088b727456dde36954ca0e68de3d783c40ffa426 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Thu, 23 Feb 2017 11:43:30 +0100 Subject: [PATCH 15/16] Add missing urls in MutexGuard docs --- src/libstd/sync/mutex.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/libstd/sync/mutex.rs b/src/libstd/sync/mutex.rs index 0d6ad5e38e98b..97b84d59218ac 100644 --- a/src/libstd/sync/mutex.rs +++ b/src/libstd/sync/mutex.rs @@ -133,11 +133,13 @@ unsafe impl Sync for Mutex { } /// dropped (falls out of scope), the lock will be unlocked. /// /// The data protected by the mutex can be access through this guard via its -/// `Deref` and `DerefMut` implementations. +/// [`Deref`] and [`DerefMut`] implementations. /// /// This structure is created by the [`lock()`] and [`try_lock()`] methods on /// [`Mutex`]. /// +/// [`Deref`]: ../../std/ops/trait.Deref.html +/// [`DerefMut`]: ../../std/ops/trait.DerefMut.html /// [`lock()`]: struct.Mutex.html#method.lock /// [`try_lock()`]: struct.Mutex.html#method.try_lock /// [`Mutex`]: struct.Mutex.html From 7c52cadfc38671147f8d9dba577c086a1cdba0ec Mon Sep 17 00:00:00 2001 From: Tom Anderson Date: Fri, 24 Feb 2017 11:48:42 +0000 Subject: [PATCH 16/16] Correct another typo in procedural macros chapter of the Book. --- src/doc/book/src/procedural-macros.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/src/procedural-macros.md b/src/doc/book/src/procedural-macros.md index 079324d56d1e6..f194c710284ca 100644 --- a/src/doc/book/src/procedural-macros.md +++ b/src/doc/book/src/procedural-macros.md @@ -170,7 +170,7 @@ a representation of our type (which can be either a `struct` or an `enum`). Check out the [docs](https://docs.rs/syn/0.10.5/syn/struct.MacroInput.html), there is some useful information there. We are able to get the name of the type using `ast.ident`. The `quote!` macro lets us write up the Rust code -that we wish to return and convert it into `Tokens`. `quote!` let's us use some +that we wish to return and convert it into `Tokens`. `quote!` lets us use some really cool templating mechanics; we simply write `#name` and `quote!` will replace it with the variable named `name`. You can even do some repetition similar to regular macros work. You should check out the