From dcee93a8030c3a62c5a05b45b050f90251d93af8 Mon Sep 17 00:00:00 2001 From: Matthew Piziak Date: Tue, 16 Aug 2016 04:11:48 -0400 Subject: [PATCH 01/11] replace Add example with something more evocative of addition Currently most of the operator traits use trivial implementation examples that only perform side effects. Honestly, that might not be too bad for the sake of documentation; but anyway, here's a proposal to move a slightly modified version of the module-level point-addition example into the `Add` documentation, since it's more evocative of addition semantics. Part of #29365 wrap identifiers in backticks minor rephrasing fix module-level documentation to be more truthful This branch changes the example for `Add` to no longer be a "minimum implementation that prints something to the screen". --- src/libcore/ops.rs | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs index 9347ac2a8c82f..9e6310ed460d2 100644 --- a/src/libcore/ops.rs +++ b/src/libcore/ops.rs @@ -62,8 +62,7 @@ //! } //! ``` //! -//! See the documentation for each trait for a minimum implementation that -//! prints something to the screen. +//! See the documentation for each trait for an example implementation. #![stable(feature = "rust1", since = "1.0.0")] @@ -166,25 +165,38 @@ macro_rules! forward_ref_binop { /// /// # Examples /// -/// A trivial implementation of `Add`. When `Foo + Foo` happens, it ends up -/// calling `add`, and therefore, `main` prints `Adding!`. +/// This example creates a `Point` struct that implements the `Add` trait, and +/// then demonstrates adding two `Point`s. /// /// ``` /// use std::ops::Add; /// -/// struct Foo; +/// #[derive(Debug)] +/// struct Point { +/// x: i32, +/// y: i32, +/// } /// -/// impl Add for Foo { -/// type Output = Foo; +/// impl Add for Point { +/// type Output = Point; /// -/// fn add(self, _rhs: Foo) -> Foo { -/// println!("Adding!"); -/// self +/// fn add(self, other: Point) -> Point { +/// Point { +/// x: self.x + other.x, +/// y: self.y + other.y, +/// } +/// } +/// } +/// +/// impl PartialEq for Point { +/// fn eq(&self, other: &Self) -> bool { +/// self.x == other.x && self.y == other.y /// } /// } /// /// fn main() { -/// Foo + Foo; +/// assert_eq!(Point { x: 1, y: 0 } + Point { x: 2, y: 3 }, +/// Point { x: 3, y: 3 }); /// } /// ``` #[lang = "add"] From 0dc13ee7f23f878e626771c1a3925b37b19fd6e4 Mon Sep 17 00:00:00 2001 From: clementmiao Date: Wed, 17 Aug 2016 22:03:52 -0700 Subject: [PATCH 02/11] updated E0395 to new error format --- src/librustc_mir/transform/qualify_consts.rs | 11 ++++++++--- src/test/compile-fail/E0395.rs | 2 +- src/test/compile-fail/issue-25826.rs | 1 + 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/src/librustc_mir/transform/qualify_consts.rs b/src/librustc_mir/transform/qualify_consts.rs index 103a15dadb61c..a9ef702ee0548 100644 --- a/src/librustc_mir/transform/qualify_consts.rs +++ b/src/librustc_mir/transform/qualify_consts.rs @@ -678,9 +678,14 @@ impl<'a, 'tcx> Visitor<'tcx> for Qualifier<'a, 'tcx, 'tcx> { self.add(Qualif::NOT_CONST); if self.mode != Mode::Fn { - span_err!(self.tcx.sess, self.span, E0395, - "raw pointers cannot be compared in {}s", - self.mode); + struct_span_err!( + self.tcx.sess, self.span, E0395, + "raw pointers cannot be compared in {}s", + self.mode) + .span_label( + self.span, + &format!("comparing raw pointers in static")) + .emit(); } } } diff --git a/src/test/compile-fail/E0395.rs b/src/test/compile-fail/E0395.rs index 6ab66313a0472..98f08cd68c22d 100644 --- a/src/test/compile-fail/E0395.rs +++ b/src/test/compile-fail/E0395.rs @@ -12,6 +12,6 @@ static FOO: i32 = 42; static BAR: i32 = 42; static BAZ: bool = { (&FOO as *const i32) == (&BAR as *const i32) }; //~ ERROR E0395 - + //~| NOTE comparing raw pointers in static fn main() { } diff --git a/src/test/compile-fail/issue-25826.rs b/src/test/compile-fail/issue-25826.rs index 00e1279d58a0e..468282fa7cca9 100644 --- a/src/test/compile-fail/issue-25826.rs +++ b/src/test/compile-fail/issue-25826.rs @@ -12,5 +12,6 @@ fn id(t: T) -> T { t } fn main() { const A: bool = id:: as *const () < id:: as *const (); //~^ ERROR raw pointers cannot be compared in constants [E0395] + //~^^ NOTE comparing raw pointers in static println!("{}", A); } From dae1406b822c1357f701047951e747dbca2b1446 Mon Sep 17 00:00:00 2001 From: clementmiao Date: Wed, 17 Aug 2016 22:45:21 -0700 Subject: [PATCH 03/11] updated E0396 to new error format --- src/librustc_mir/transform/qualify_consts.rs | 10 +++++++--- src/test/compile-fail/E0396.rs | 1 + src/test/compile-fail/const-deref-ptr.rs | 1 + 3 files changed, 9 insertions(+), 3 deletions(-) diff --git a/src/librustc_mir/transform/qualify_consts.rs b/src/librustc_mir/transform/qualify_consts.rs index 103a15dadb61c..e5473d288d4f3 100644 --- a/src/librustc_mir/transform/qualify_consts.rs +++ b/src/librustc_mir/transform/qualify_consts.rs @@ -490,9 +490,13 @@ impl<'a, 'tcx> Visitor<'tcx> for Qualifier<'a, 'tcx, 'tcx> { if let ty::TyRawPtr(_) = base_ty.sty { this.add(Qualif::NOT_CONST); if this.mode != Mode::Fn { - span_err!(this.tcx.sess, this.span, E0396, - "raw pointers cannot be dereferenced in {}s", - this.mode); + struct_span_err!(this.tcx.sess, + this.span, E0396, + "raw pointers cannot be dereferenced in {}s", + this.mode) + .span_label(this.span, + &format!("dereference of raw pointer in constant")) + .emit(); } } } diff --git a/src/test/compile-fail/E0396.rs b/src/test/compile-fail/E0396.rs index 7f34acdfb9007..47080fb6e9ef7 100644 --- a/src/test/compile-fail/E0396.rs +++ b/src/test/compile-fail/E0396.rs @@ -11,6 +11,7 @@ const REG_ADDR: *const u8 = 0x5f3759df as *const u8; const VALUE: u8 = unsafe { *REG_ADDR }; //~ ERROR E0396 + //~| NOTE dereference of raw pointer in constant fn main() { } diff --git a/src/test/compile-fail/const-deref-ptr.rs b/src/test/compile-fail/const-deref-ptr.rs index fa15f3e87c694..c626801d48c03 100644 --- a/src/test/compile-fail/const-deref-ptr.rs +++ b/src/test/compile-fail/const-deref-ptr.rs @@ -12,5 +12,6 @@ fn main() { static C: u64 = unsafe {*(0xdeadbeef as *const u64)}; //~ ERROR E0396 + //~| NOTE dereference of raw pointer in constant println!("{}", C); } From 6976991569977e8097da5f7660a31a42d11e48d2 Mon Sep 17 00:00:00 2001 From: Erik Uggeldahl Date: Thu, 18 Aug 2016 02:03:42 -0400 Subject: [PATCH 04/11] Fix tiny spelling mistake in book Changed datastructure to data structure --- src/doc/book/borrow-and-asref.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/book/borrow-and-asref.md b/src/doc/book/borrow-and-asref.md index 1cfeb2620bd08..c30b2e68665f1 100644 --- a/src/doc/book/borrow-and-asref.md +++ b/src/doc/book/borrow-and-asref.md @@ -8,7 +8,7 @@ different. Here’s a quick refresher on what these two traits mean. # Borrow -The `Borrow` trait is used when you’re writing a datastructure, and you want to +The `Borrow` trait is used when you’re writing a data structure, and you want to use either an owned or borrowed type as synonymous for some purpose. For example, [`HashMap`][hashmap] has a [`get` method][get] which uses `Borrow`: @@ -86,7 +86,7 @@ We can see how they’re kind of the same: they both deal with owned and borrowe versions of some type. However, they’re a bit different. Choose `Borrow` when you want to abstract over different kinds of borrowing, or -when you’re building a datastructure that treats owned and borrowed values in +when you’re building a data structure that treats owned and borrowed values in equivalent ways, such as hashing and comparison. Choose `AsRef` when you want to convert something to a reference directly, and From c2b6f7211472d5e1321e9836f5b339aec1d916d8 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Wed, 17 Aug 2016 22:56:43 -0400 Subject: [PATCH 05/11] Add a few doc examples for `std::ffi::OsStr`. * `std::ffi::OsStr::new`. * `std::ffi::OsStr::is_empty`. * `std::ffi::OsStr::len`. --- src/libstd/ffi/os_str.rs | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/src/libstd/ffi/os_str.rs b/src/libstd/ffi/os_str.rs index 0d29e62485abb..3d23a9a2383ff 100644 --- a/src/libstd/ffi/os_str.rs +++ b/src/libstd/ffi/os_str.rs @@ -251,6 +251,14 @@ impl Hash for OsString { impl OsStr { /// Coerces into an `OsStr` slice. + /// + /// # Examples + /// + /// ``` + /// use std::ffi::OsStr; + /// + /// let os_str = OsStr::new("foo"); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn new + ?Sized>(s: &S) -> &OsStr { s.as_ref() @@ -283,6 +291,18 @@ impl OsStr { } /// Checks whether the `OsStr` is empty. + /// + /// # Examples + /// + /// ``` + /// use std::ffi::OsStr; + /// + /// let os_str = OsStr::new(""); + /// assert!(os_str.is_empty()); + /// + /// let os_str = OsStr::new("foo"); + /// assert!(!os_str.is_empty()); + /// ``` #[stable(feature = "osstring_simple_functions", since = "1.9.0")] pub fn is_empty(&self) -> bool { self.inner.inner.is_empty() @@ -296,6 +316,18 @@ impl OsStr { /// other methods like `OsString::with_capacity` to avoid reallocations. /// /// See `OsStr` introduction for more information about encoding. + /// + /// # Examples + /// + /// ``` + /// use std::ffi::OsStr; + /// + /// let os_str = OsStr::new(""); + /// assert_eq!(os_str.len(), 0); + /// + /// let os_str = OsStr::new("foo"); + /// assert_eq!(os_str.len(), 3); + /// ``` #[stable(feature = "osstring_simple_functions", since = "1.9.0")] pub fn len(&self) -> usize { self.inner.inner.len() From d56f9ff040f44e2abfd08ba032fb361ee7485d2c Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Thu, 18 Aug 2016 17:50:28 +0200 Subject: [PATCH 06/11] Improve Path and PathBuf docs --- src/libstd/fs.rs | 7 +- src/libstd/path.rs | 174 +++++++++++++++++++++++++++++++++++++-------- 2 files changed, 148 insertions(+), 33 deletions(-) diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index b78db24e44b70..ed821983b7087 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -1511,8 +1511,11 @@ pub fn remove_dir_all>(path: P) -> io::Result<()> { /// Returns an iterator over the entries within a directory. /// -/// The iterator will yield instances of `io::Result`. New errors may -/// be encountered after an iterator is initially constructed. +/// The iterator will yield instances of [`io::Result<`][`DirEntry`]`>`. +/// New errors may be encountered after an iterator is initially constructed. +/// +/// [`io::Result<`]: ../io/type.Result.html +/// [`DirEntry`]: ../fs/struct.DirEntry.html /// /// # Platform-specific behavior /// diff --git a/src/libstd/path.rs b/src/libstd/path.rs index 2d19561139b58..4731cce483172 100644 --- a/src/libstd/path.rs +++ b/src/libstd/path.rs @@ -986,11 +986,16 @@ impl<'a> cmp::Ord for Components<'a> { // Basic types and traits //////////////////////////////////////////////////////////////////////////////// -/// An owned, mutable path (akin to `String`). +/// An owned, mutable path (akin to [`String`]). /// -/// This type provides methods like `push` and `set_extension` that mutate the -/// path in place. It also implements `Deref` to `Path`, meaning that all -/// methods on `Path` slices are available on `PathBuf` values as well. +/// This type provides methods like [`push`] and [`set_extension`] that mutate +/// the path in place. It also implements [`Deref`] to [`Path`], meaning that +/// all methods on [`Path`] slices are available on `PathBuf` values as well. +/// +/// [`String`]: ../string/struct.String.html +/// [`Path`]: struct.Path.html +/// [`push`]: struct.PathBuf.html#method.push +/// [`set_extension`]: struct.PathBuf.html#method.set_extension /// /// More details about the overall approach can be found in /// the module documentation. @@ -1017,12 +1022,31 @@ impl PathBuf { } /// Allocates an empty `PathBuf`. + /// + /// # Examples + /// + /// ``` + /// use std::path::PathBuf; + /// + /// let path = PathBuf::new(); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn new() -> PathBuf { PathBuf { inner: OsString::new() } } - /// Coerces to a `Path` slice. + /// Coerces to a [`Path`] slice. + /// + /// [`Path`]: struct.Path.html + /// + /// # Examples + /// + /// ``` + /// use std::path::{Path, PathBuf}; + /// + /// let p = PathBuf::from("/test"); + /// assert_eq!(Path::new("/test"), p.as_path()); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn as_path(&self) -> &Path { self @@ -1087,10 +1111,26 @@ impl PathBuf { self.inner.push(path); } - /// Truncate `self` to `self.parent()`. + /// Truncate `self` to [`self.parent()`]. /// - /// Returns false and does nothing if `self.file_name()` is `None`. + /// Returns false and does nothing if [`self.file_name()`] is `None`. /// Otherwise, returns `true`. + /// + /// [`self.parent()`]: struct.PathBuf.html#method.parent + /// [`self.file_name()`]: struct.PathBuf.html#method.file_name + /// + /// # Examples + /// + /// ``` + /// use std::path::PathBuf; + /// + /// let mut p = PathBuf::from("/test/test.rs"); + /// + /// p.pop(); + /// assert_eq!(Path::new("/test"), p.as_path()); + /// p.pop(); + /// assert_eq!(Path::new("/"), p.as_path()); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn pop(&mut self) -> bool { match self.parent().map(|p| p.as_u8_slice().len()) { @@ -1102,11 +1142,13 @@ impl PathBuf { } } - /// Updates `self.file_name()` to `file_name`. + /// Updates [`self.file_name()`] to `file_name`. /// /// If `self.file_name()` was `None`, this is equivalent to pushing /// `file_name`. /// + /// [`self.file_name()`]: struct.PathBuf.html#method.file_name + /// /// # Examples /// /// ``` @@ -1133,12 +1175,29 @@ impl PathBuf { self.push(file_name); } - /// Updates `self.extension()` to `extension`. + /// Updates [`self.extension()`] to `extension`. + /// + /// If [`self.file_name()`] is `None`, does nothing and returns `false`. + /// + /// Otherwise, returns `true`; if [`self.extension()`] is `None`, the + /// extension is added; otherwise it is replaced. + /// + /// [`self.file_name()`]: struct.PathBuf.html#method.file_name + /// [`self.extension()`]: struct.PathBuf.html#method.extension + /// + /// # Examples + /// + /// ``` + /// use std::path::PathBuf; /// - /// If `self.file_name()` is `None`, does nothing and returns `false`. + /// let mut p = PathBuf::from("/feel/the"); /// - /// Otherwise, returns `true`; if `self.extension()` is `None`, the extension - /// is added; otherwise it is replaced. + /// p.set_extension("force"); + /// assert_eq!(Path::new("/feel/the.force"), p.as_path()); + /// + /// p.set_extension("dark_side"); + /// assert_eq!(Path::new("/feel/the.dark_side"), p.as_path()); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn set_extension>(&mut self, extension: S) -> bool { self._set_extension(extension.as_ref()) @@ -1163,7 +1222,18 @@ impl PathBuf { true } - /// Consumes the `PathBuf`, yielding its internal `OsString` storage. + /// Consumes the `PathBuf`, yielding its internal [`OsString`] storage. + /// + /// [`OsString`]: ../ffi/struct.OsString.html + /// + /// # Examples + /// + /// ``` + /// use std::path::PathBuf; + /// + /// let p = PathBuf::from("/the/head"); + /// let os_str = p.into_os_string(); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn into_os_string(self) -> OsString { self.inner @@ -1301,7 +1371,7 @@ impl Into for PathBuf { } } -/// A slice of a path (akin to `str`). +/// A slice of a path (akin to [`str`]). /// /// This type supports a number of operations for inspecting a path, including /// breaking the path into its components (separated by `/` or `\`, depending on @@ -1310,7 +1380,10 @@ impl Into for PathBuf { /// the module documentation. /// /// This is an *unsized* type, meaning that it must always be used behind a -/// pointer like `&` or `Box`. +/// pointer like `&` or [`Box`]. +/// +/// [`str`]: ../primitive.str.html +/// [`Box`]: ../boxed/struct.Box.html /// /// # Examples /// @@ -1372,7 +1445,9 @@ impl Path { unsafe { mem::transmute(s.as_ref()) } } - /// Yields the underlying `OsStr` slice. + /// Yields the underlying [`OsStr`] slice. + /// + /// [`OsStr`]: ../ffi/struct.OsStr.html /// /// # Examples /// @@ -1387,10 +1462,12 @@ impl Path { &self.inner } - /// Yields a `&str` slice if the `Path` is valid unicode. + /// Yields a [`&str`] slice if the `Path` is valid unicode. /// /// This conversion may entail doing a check for UTF-8 validity. /// + /// [`&str`]: ../primitive.str.html + /// /// # Examples /// /// ``` @@ -1404,10 +1481,12 @@ impl Path { self.inner.to_str() } - /// Converts a `Path` to a `Cow`. + /// Converts a `Path` to a [`Cow`]. /// /// Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER. /// + /// [`Cow`]: ../borrow/enum.Cow.html + /// /// # Examples /// /// ``` @@ -1421,7 +1500,9 @@ impl Path { self.inner.to_string_lossy() } - /// Converts a `Path` to an owned `PathBuf`. + /// Converts a `Path` to an owned [`PathBuf`]. + /// + /// [`PathBuf`]: struct.PathBuf.html /// /// # Examples /// @@ -1569,6 +1650,18 @@ impl Path { /// /// If `base` is not a prefix of `self` (i.e. `starts_with` /// returns `false`), returns `Err`. + /// + /// # Examples + /// + /// ``` + /// use std::path::Path; + /// + /// let path = Path::new("/test/haha/foo.txt"); + /// + /// assert_eq!(path.strip_prefix("/test"), Ok(Path::new("haha/foo.txt"))); + /// assert_eq!(path.strip_prefix("test").is_ok(), false); + /// assert_eq!(path.strip_prefix("/haha").is_ok(), false); + /// ``` #[stable(since = "1.7.0", feature = "path_strip_prefix")] pub fn strip_prefix<'a, P: ?Sized>(&'a self, base: &'a P) -> Result<&'a Path, StripPrefixError> @@ -1630,7 +1723,9 @@ impl Path { iter_after(self.components().rev(), child.components().rev()).is_some() } - /// Extracts the stem (non-extension) portion of `self.file_name()`. + /// Extracts the stem (non-extension) portion of [`self.file_name()`]. + /// + /// [`self.file_name()`]: struct.Path.html#method.file_name /// /// The stem is: /// @@ -1653,7 +1748,9 @@ impl Path { self.file_name().map(split_file_at_dot).and_then(|(before, after)| before.or(after)) } - /// Extracts the extension of `self.file_name()`, if possible. + /// Extracts the extension of [`self.file_name()`], if possible. + /// + /// [`self.file_name()`]: struct.Path.html#method.file_name /// /// The extension is: /// @@ -1676,9 +1773,12 @@ impl Path { self.file_name().map(split_file_at_dot).and_then(|(before, after)| before.and(after)) } - /// Creates an owned `PathBuf` with `path` adjoined to `self`. + /// Creates an owned [`PathBuf`] with `path` adjoined to `self`. + /// + /// See [`PathBuf::push`] for more details on what it means to adjoin a path. /// - /// See `PathBuf::push` for more details on what it means to adjoin a path. + /// [`PathBuf`]: struct.PathBuf.html + /// [`PathBuf::push`]: struct.PathBuf.html#method.push /// /// # Examples /// @@ -1698,9 +1798,12 @@ impl Path { buf } - /// Creates an owned `PathBuf` like `self` but with the given file name. + /// Creates an owned [`PathBuf`] like `self` but with the given file name. /// - /// See `PathBuf::set_file_name` for more details. + /// See [`PathBuf::set_file_name`] for more details. + /// + /// [`PathBuf`]: struct.PathBuf.html + /// [`PathBuf::set_file_name`]: struct.PathBuf.html#method.set_file_name /// /// # Examples /// @@ -1721,9 +1824,12 @@ impl Path { buf } - /// Creates an owned `PathBuf` like `self` but with the given extension. + /// Creates an owned [`PathBuf`] like `self` but with the given extension. + /// + /// See [`PathBuf::set_extension`] for more details. /// - /// See `PathBuf::set_extension` for more details. + /// [`PathBuf`]: struct.PathBuf.html + /// [`PathBuf::set_extension`]: struct.PathBuf.html#method.set_extension /// /// # Examples /// @@ -1771,7 +1877,9 @@ impl Path { } } - /// Produce an iterator over the path's components viewed as `OsStr` slices. + /// Produce an iterator over the path's components viewed as [`OsStr`] slices. + /// + /// [`OsStr`]: ffi/struct.OsStr.html /// /// # Examples /// @@ -1790,9 +1898,11 @@ impl Path { Iter { inner: self.components() } } - /// Returns an object that implements `Display` for safely printing paths + /// Returns an object that implements [`Display`] for safely printing paths /// that may contain non-Unicode data. /// + /// [`Display`]: fmt/trait.Display.html + /// /// # Examples /// /// ``` @@ -1854,11 +1964,13 @@ impl Path { /// Returns an iterator over the entries within a directory. /// - /// The iterator will yield instances of `io::Result`. New errors may - /// be encountered after an iterator is initially constructed. + /// The iterator will yield instances of [`io::Result<`][`DirEntry`]`>`. New + /// errors may be encountered after an iterator is initially constructed. /// /// This is an alias to [`fs::read_dir`]. /// + /// [`io::Result<`]: ../io/type.Result.html + /// [`DirEntry`]: ../fs/struct.DirEntry.html /// [`fs::read_dir`]: ../fs/fn.read_dir.html #[stable(feature = "path_ext", since = "1.5.0")] pub fn read_dir(&self) -> io::Result { From 06302cb983198bdf6b984510d24673f4d0f49a98 Mon Sep 17 00:00:00 2001 From: Andrew Cantino Date: Thu, 18 Aug 2016 15:06:05 -0400 Subject: [PATCH 07/11] Fix minor typo --- src/doc/book/closures.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/closures.md b/src/doc/book/closures.md index d332cac7d8d16..3ed85c1a90b69 100644 --- a/src/doc/book/closures.md +++ b/src/doc/book/closures.md @@ -340,7 +340,7 @@ fn call_with_ref<'a, F>(some_closure:F) -> i32 where F: Fn(&'a i32) -> i32 { ``` -However this presents a problem with in our case. When you specify the explicit +However this presents a problem in our case. When you specify the explicit lifetime on a function it binds that lifetime to the *entire* scope of the function instead of just the invocation scope of our closure. This means that the borrow checker will see a mutable reference in the same lifetime as our immutable reference and fail From 96bd6cfcb045b962ab77c826618b56eec011f99f Mon Sep 17 00:00:00 2001 From: Matthew Piziak Date: Thu, 18 Aug 2016 15:10:57 -0400 Subject: [PATCH 08/11] demonstrate `RHS != Self` use cases for `Add` and `Sub` --- src/libcore/ops.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs index 9347ac2a8c82f..edd1fe9265331 100644 --- a/src/libcore/ops.rs +++ b/src/libcore/ops.rs @@ -187,6 +187,12 @@ macro_rules! forward_ref_binop { /// Foo + Foo; /// } /// ``` +/// +/// Note that `RHS = Self` by default, but this is not mandatory. For example, +/// [std::time::SystemTime] implements `Add`, which permits +/// operations of the form `SystemTime = SystemTime + Duration`. +/// +/// [std::time::SystemTime]: ../../time/struct.SystemTime.html #[lang = "add"] #[stable(feature = "rust1", since = "1.0.0")] pub trait Add { @@ -241,6 +247,12 @@ add_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 } /// Foo - Foo; /// } /// ``` +/// +/// Note that `RHS = Self` by default, but this is not mandatory. For example, +/// [std::time::SystemTime] implements `Sub`, which permits +/// operations of the form `SystemTime = SystemTime - Duration`. +/// +/// [std::time::SystemTime]: ../../time/struct.SystemTime.html #[lang = "sub"] #[stable(feature = "rust1", since = "1.0.0")] pub trait Sub { From 161cb36159337edfeba546c9ead24262bc5a5dfc Mon Sep 17 00:00:00 2001 From: pliniker Date: Thu, 18 Aug 2016 16:27:33 -0400 Subject: [PATCH 09/11] Update error message for E0084 --- src/librustc_typeck/check/mod.rs | 7 +++++-- src/test/compile-fail/E0084.rs | 4 +++- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/src/librustc_typeck/check/mod.rs b/src/librustc_typeck/check/mod.rs index ff0b86aa59540..78d311865aa87 100644 --- a/src/librustc_typeck/check/mod.rs +++ b/src/librustc_typeck/check/mod.rs @@ -1245,8 +1245,11 @@ pub fn check_enum_variants<'a,'tcx>(ccx: &CrateCtxt<'a,'tcx>, let hint = *ccx.tcx.lookup_repr_hints(def_id).get(0).unwrap_or(&attr::ReprAny); if hint != attr::ReprAny && vs.is_empty() { - span_err!(ccx.tcx.sess, sp, E0084, - "unsupported representation for zero-variant enum"); + struct_span_err!( + ccx.tcx.sess, sp, E0084, + "unsupported representation for zero-variant enum") + .span_label(sp, &format!("unsupported enum representation")) + .emit(); } let repr_type_ty = ccx.tcx.enum_repr_type(Some(&hint)).to_ty(ccx.tcx); diff --git a/src/test/compile-fail/E0084.rs b/src/test/compile-fail/E0084.rs index c579101325f5d..c7c5662f1feda 100644 --- a/src/test/compile-fail/E0084.rs +++ b/src/test/compile-fail/E0084.rs @@ -9,7 +9,9 @@ // except according to those terms. #[repr(i32)] -enum Foo {} //~ ERROR E0084 +enum Foo {} +//~^ ERROR E0084 +//~| unsupported enum representation fn main() { } From a516dbb7d946fc26ed036ae4bd23f4c7abdff3a2 Mon Sep 17 00:00:00 2001 From: Matthew Piziak Date: Tue, 16 Aug 2016 04:33:59 -0400 Subject: [PATCH 10/11] note that calling drop() explicitly is a compiler error Part of #29365 explain that std::mem::drop in prelude will invoke Drop change "prelude" -> "the prelude"; change links to reference-style move link references to links' section --- src/libcore/ops.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs index 9347ac2a8c82f..daa5ebb61f96d 100644 --- a/src/libcore/ops.rs +++ b/src/libcore/ops.rs @@ -102,6 +102,13 @@ pub trait Drop { /// /// After this function is over, the memory of `self` will be deallocated. /// + /// This function cannot be called explicitly. This is compiler error + /// [0040]. However, the [`std::mem::drop`] function in the prelude can be + /// used to call the argument's `Drop` implementation. + /// + /// [0040]: https://doc.rust-lang.org/error-index.html#E0040 + /// [`std::mem::drop`]: https://doc.rust-lang.org/std/mem/fn.drop.html + /// /// # Panics /// /// Given that a `panic!` will call `drop()` as it unwinds, any `panic!` in From 6c66eaa035e5fc47ebbff44b81d2cb3cf1d7d568 Mon Sep 17 00:00:00 2001 From: Matthew Piziak Date: Thu, 18 Aug 2016 16:54:33 -0400 Subject: [PATCH 11/11] replace `AddAssign` example with something more evocative of addition This is analogous to PR #35709 for the `Add` trait. --- src/libcore/ops.rs | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs index 9347ac2a8c82f..1a203a898f73e 100644 --- a/src/libcore/ops.rs +++ b/src/libcore/ops.rs @@ -894,25 +894,36 @@ shr_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize } /// /// # Examples /// -/// A trivial implementation of `AddAssign`. When `Foo += Foo` happens, it ends up -/// calling `add_assign`, and therefore, `main` prints `Adding!`. +/// This example creates a `Point` struct that implements the `AddAssign` +/// trait, and then demonstrates add-assigning to a mutable `Point`. /// /// ``` /// use std::ops::AddAssign; /// -/// struct Foo; +/// #[derive(Debug)] +/// struct Point { +/// x: i32, +/// y: i32, +/// } /// -/// impl AddAssign for Foo { -/// fn add_assign(&mut self, _rhs: Foo) { -/// println!("Adding!"); +/// impl AddAssign for Point { +/// fn add_assign(&mut self, other: Point) { +/// *self = Point { +/// x: self.x + other.x, +/// y: self.y + other.y, +/// }; /// } /// } /// -/// # #[allow(unused_assignments)] -/// fn main() { -/// let mut foo = Foo; -/// foo += Foo; +/// impl PartialEq for Point { +/// fn eq(&self, other: &Self) -> bool { +/// self.x == other.x && self.y == other.y +/// } /// } +/// +/// let mut point = Point { x: 1, y: 0 }; +/// point += Point { x: 2, y: 3 }; +/// assert_eq!(point, Point { x: 3, y: 3 }); /// ``` #[lang = "add_assign"] #[stable(feature = "op_assign_traits", since = "1.8.0")]