Auto merge of #75692 - JohnTitor:rollup-8gr04ah, r=JohnTitor

Rollup of 9 pull requests

Successful merges:

 - #75038 (See also X-Link mem::{swap, take, replace})
 - #75049 (docs(marker/copy): provide example for `&T` being `Copy`)
 - #75499 (Fix documentation error)
 - #75554 (Fix clashing_extern_declarations stack overflow for recursive types.)
 - #75646 (Move to intra doc links for keyword documentation)
 - #75652 (Resolve true and false as booleans)
 - #75658 (Don't emit "is not a logical operator" error outside of associative expressions)
 - #75665 (Add doc examples coverage)
 - #75685 (Switch to intra-doc links in /src/sys/unix/ext/*.rs)

Failed merges:

r? @ghost

Author: bors

library/core/src/marker.rs

@@ -291,6 +291,7 @@ pub trait StructuralEq {
 ///
 /// ```
 /// # #[allow(dead_code)]
+/// #[derive(Copy, Clone)]
 /// struct Point {
 ///    x: i32,
 ///    y: i32,
@@ -315,6 +316,20 @@ pub trait StructuralEq {
 /// the trait `Copy` may not be implemented for this type; field `points` does not implement `Copy`
 /// ```
 ///
+/// Shared references (`&T`) are also `Copy`, so a type can be `Copy`, even when it holds
+/// shared references of types `T` that are *not* `Copy`. Consider the following struct,
+/// which can implement `Copy`, because it only holds a *shared reference* to our non-`Copy`
+/// type `PointList` from above:
+///
+/// ```
+/// # #![allow(dead_code)]
+/// # struct PointList;
+/// #[derive(Copy, Clone)]
+/// struct PointListWrapper<'a> {
+///     point_list_ref: &'a PointList,
+/// }
+/// ```
+///
 /// ## When *can't* my type be `Copy`?
 ///
 /// Some types can't be copied safely. For example, copying `&mut T` would create an aliased

library/core/src/mem/mod.rs

@@ -670,6 +670,9 @@ pub unsafe fn uninitialized<T>() -> T {
 
 /// Swaps the values at two mutable locations, without deinitializing either one.
 ///
+/// * If you want to swap with a default or dummy value, see [`take`].
+/// * If you want to swap with a passed value, returning the old value, see [`replace`].
+///
 /// # Examples
 ///
 /// ```
@@ -683,6 +686,9 @@ pub unsafe fn uninitialized<T>() -> T {
 /// assert_eq!(42, x);
 /// assert_eq!(5, y);
 /// ```
+///
+/// [`replace`]: fn.replace.html
+/// [`take`]: fn.take.html
 #[inline]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub fn swap<T>(x: &mut T, y: &mut T) {
@@ -695,6 +701,9 @@ pub fn swap<T>(x: &mut T, y: &mut T) {
 
 /// Replaces `dest` with the default value of `T`, returning the previous `dest` value.
 ///
+/// * If you want to replace the values of two variables, see [`swap`].
+/// * If you want to replace with a passed value instead of the default value, see [`replace`].
+///
 /// # Examples
 ///
 /// A simple example:
@@ -747,6 +756,8 @@ pub fn swap<T>(x: &mut T, y: &mut T) {
 /// ```
 ///
 /// [`Clone`]: ../../std/clone/trait.Clone.html
+/// [`replace`]: fn.replace.html
+/// [`swap`]: fn.swap.html
 #[inline]
 #[stable(feature = "mem_take", since = "1.40.0")]
 pub fn take<T: Default>(dest: &mut T) -> T {
@@ -757,6 +768,9 @@ pub fn take<T: Default>(dest: &mut T) -> T {
 ///
 /// Neither value is dropped.
 ///
+/// * If you want to replace the values of two variables, see [`swap`].
+/// * If you want to replace with a default value, see [`take`].
+///
 /// # Examples
 ///
 /// A simple example:
@@ -810,6 +824,8 @@ pub fn take<T: Default>(dest: &mut T) -> T {
 /// ```
 ///
 /// [`Clone`]: ../../std/clone/trait.Clone.html
+/// [`swap`]: fn.swap.html
+/// [`take`]: fn.take.html
 #[inline]
 #[stable(feature = "rust1", since = "1.0.0")]
 #[must_use = "if you don't need the old value, you can just assign the new value directly"]

library/core/src/str/mod.rs

@@ -2031,7 +2031,7 @@ mod traits {
     /// # Panics
     ///
     /// Panics if `begin` does not point to the starting byte offset of
-    /// a character (as defined by `is_char_boundary`), or if `begin >= len`.
+    /// a character (as defined by `is_char_boundary`), or if `begin > len`.
     #[stable(feature = "str_checked_slicing", since = "1.20.0")]
     unsafe impl SliceIndex<str> for ops::RangeFrom<usize> {
         type Output = str;

library/std/src/keyword_docs.rs

@@ -98,7 +98,6 @@ mod as_keyword {}
 /// [Reference on "break expression"]: ../reference/expressions/loop-expr.html#break-expressions
 /// [Reference on "break and loop values"]:
 /// ../reference/expressions/loop-expr.html#break-and-loop-values
-///
 mod break_keyword {}
 
 #[doc(keyword = "const")]
@@ -336,7 +335,6 @@ mod else_keyword {}
 /// For more information, take a look at the [Rust Book] or the [Reference]
 ///
 /// [ADT]: https://en.wikipedia.org/wiki/Algebraic_data_type
-/// [`Option`]: option/enum.Option.html
 /// [Rust Book]: ../book/ch06-01-defining-an-enum.html
 /// [Reference]: ../reference/items/enumerations.html
 mod enum_keyword {}
@@ -534,7 +532,6 @@ mod fn_keyword {}
 /// [`in`]: keyword.in.html
 /// [`impl`]: keyword.impl.html
 /// [higher-ranked trait bounds]: ../reference/trait-bounds.html#higher-ranked-trait-bounds
-/// [`IntoIterator`]: iter/trait.IntoIterator.html
 /// [Rust book]:
 /// ../book/ch03-05-control-flow.html#looping-through-a-collection-with-for
 /// [Reference]: ../reference/expressions/loop-expr.html#iterator-loops
@@ -993,7 +990,6 @@ mod mod_keyword {}
 /// For more information on the `move` keyword, see the [closure]'s section
 /// of the Rust book or the [threads] section
 ///
-/// [`Fn` trait]: ../std/ops/trait.Fn.html
 /// [closure]: ../book/ch13-01-closures.html
 /// [threads]: ../book/ch16-01-threads.html#using-move-closures-with-threads
 mod move_keyword {}
@@ -1413,9 +1409,7 @@ mod self_upper_keyword {}
 /// [`extern`]: keyword.extern.html
 /// [`mut`]: keyword.mut.html
 /// [`unsafe`]: keyword.unsafe.html
-/// [`drop`]: mem/fn.drop.html
-/// [`Sync`]: marker/trait.Sync.html
-/// [`RefCell`]: cell/struct.RefCell.html
+/// [`RefCell`]: cell::RefCell
 /// [Reference]: ../reference/items/static-items.html
 mod static_keyword {}
 
@@ -1522,7 +1516,7 @@ mod static_keyword {}
 /// For more information on structs, take a look at the [Rust Book][book] or the
 /// [Reference][reference].
 ///
-/// [`PhantomData`]: marker/struct.PhantomData.html
+/// [`PhantomData`]: marker::PhantomData
 /// [book]: ../book/ch05-01-defining-structs.html
 /// [reference]: ../reference/items/structs.html
 mod struct_keyword {}
@@ -1733,8 +1727,6 @@ mod super_keyword {}
 /// [`for`]: keyword.for.html
 /// [`impl`]: keyword.impl.html
 /// [`unsafe`]: keyword.unsafe.html
-/// [`Send`]: marker/trait.Send.html
-/// [`Sync`]: marker/trait.Sync.html
 /// [Ref-Traits]: ../reference/items/traits.html
 /// [Ref-Trait-Objects]: ../reference/types/trait-object.html
 mod trait_keyword {}
@@ -1764,7 +1756,6 @@ mod trait_keyword {}
 /// [`while`]: keyword.while.html
 /// [`match`]: ../reference/expressions/match-expr.html#match-guards
 /// [`false`]: keyword.false.html
-/// [`bool`]: primitive.bool.html
 mod true_keyword {}
 
 #[doc(keyword = "type")]
@@ -1986,9 +1977,6 @@ mod type_keyword {}
 /// [`static`]: keyword.static.html
 /// [`union`]: keyword.union.html
 /// [`impl`]: keyword.impl.html
-/// [Send]: marker/trait.Send.html
-/// [Sync]: marker/trait.Sync.html
-/// [`Vec::set_len`]: vec/struct.Vec.html#method.set_len
 /// [raw pointers]: ../reference/types/pointer.html
 /// [memory safety]: ../book/ch19-01-unsafe-rust.html
 /// [Rustnomicon]: ../nomicon/index.html
@@ -2178,7 +2166,7 @@ mod where_keyword {}
 ///
 /// It is available for use in stable rust from version 1.39 onwards.
 ///
-/// [`Future`]: ./future/trait.Future.html
+/// [`Future`]: future::Future
 /// [async book]: https://rust-lang.github.io/async-book/
 mod async_keyword {}
 
@@ -2197,7 +2185,7 @@ mod async_keyword {}
 ///
 /// It is available for use in stable rust from version 1.39 onwards.
 ///
-/// [`Future`]: ./future/trait.Future.html
+/// [`Future`]: future::Future
 /// [async book]: https://rust-lang.github.io/async-book/
 mod await_keyword {}
 

library/std/src/sys/unix/ext/fs.rs

@@ -9,9 +9,7 @@ use crate::sys;
 use crate::sys::platform::fs::MetadataExt as UnixMetadataExt;
 use crate::sys_common::{AsInner, AsInnerMut, FromInner};
 
-/// Unix-specific extensions to [`File`].
-///
-/// [`File`]: ../../../../std/fs/struct.File.html
+/// Unix-specific extensions to [`fs::File`].
 #[stable(feature = "file_offset", since = "1.15.0")]
 pub trait FileExt {
     /// Reads a number of bytes starting from a given offset.
@@ -55,19 +53,18 @@ pub trait FileExt {
     ///
     /// The current file cursor is not affected by this function.
     ///
-    /// Similar to [`Read::read_exact`] but uses [`read_at`] instead of `read`.
+    /// Similar to [`io::Read::read_exact`] but uses [`read_at`] instead of `read`.
     ///
-    /// [`Read::read_exact`]: ../../../../std/io/trait.Read.html#method.read_exact
-    /// [`read_at`]: #tymethod.read_at
+    /// [`read_at`]: FileExt::read_at
     ///
     /// # Errors
     ///
     /// If this function encounters an error of the kind
-    /// [`ErrorKind::Interrupted`] then the error is ignored and the operation
+    /// [`io::ErrorKind::Interrupted`] then the error is ignored and the operation
     /// will continue.
     ///
     /// If this function encounters an "end of file" before completely filling
-    /// the buffer, it returns an error of the kind [`ErrorKind::UnexpectedEof`].
+    /// the buffer, it returns an error of the kind [`io::ErrorKind::UnexpectedEof`].
     /// The contents of `buf` are unspecified in this case.
     ///
     /// If any other read error is encountered then this function immediately
@@ -77,9 +74,6 @@ pub trait FileExt {
     /// has read, but it will never read more than would be necessary to
     /// completely fill the buffer.
     ///
-    /// [`ErrorKind::Interrupted`]: ../../../../std/io/enum.ErrorKind.html#variant.Interrupted
-    /// [`ErrorKind::UnexpectedEof`]: ../../../../std/io/enum.ErrorKind.html#variant.UnexpectedEof
-    ///
     /// # Examples
     ///
     /// ```no_run
@@ -161,19 +155,18 @@ pub trait FileExt {
     /// The current file cursor is not affected by this function.
     ///
     /// This method will continuously call [`write_at`] until there is no more data
-    /// to be written or an error of non-[`ErrorKind::Interrupted`] kind is
+    /// to be written or an error of non-[`io::ErrorKind::Interrupted`] kind is
     /// returned. This method will not return until the entire buffer has been
     /// successfully written or such an error occurs. The first error that is
-    /// not of [`ErrorKind::Interrupted`] kind generated from this method will be
+    /// not of [`io::ErrorKind::Interrupted`] kind generated from this method will be
     /// returned.
     ///
     /// # Errors
     ///
     /// This function will return the first error of
-    /// non-[`ErrorKind::Interrupted`] kind that [`write_at`] returns.
+    /// non-[`io::ErrorKind::Interrupted`] kind that [`write_at`] returns.
     ///
-    /// [`ErrorKind::Interrupted`]: ../../../../std/io/enum.ErrorKind.html#variant.Interrupted
-    /// [`write_at`]: #tymethod.write_at
+    /// [`write_at`]: FileExt::write_at
     ///
     /// # Examples
     ///
@@ -223,8 +216,6 @@ impl FileExt for fs::File {
 }
 
 /// Unix-specific extensions to [`fs::Permissions`].
-///
-/// [`fs::Permissions`]: ../../../../std/fs/struct.Permissions.html
 #[stable(feature = "fs_ext", since = "1.1.0")]
 pub trait PermissionsExt {
     /// Returns the underlying raw `st_mode` bits that contain the standard
@@ -302,8 +293,6 @@ impl PermissionsExt for Permissions {
 }
 
 /// Unix-specific extensions to [`fs::OpenOptions`].
-///
-/// [`fs::OpenOptions`]: ../../../../std/fs/struct.OpenOptions.html
 #[stable(feature = "fs_ext", since = "1.1.0")]
 pub trait OpenOptionsExt {
     /// Sets the mode bits that a new file will be created with.
@@ -372,8 +361,6 @@ impl OpenOptionsExt for OpenOptions {
 }
 
 /// Unix-specific extensions to [`fs::Metadata`].
-///
-/// [`fs::Metadata`]: ../../../../std/fs/struct.Metadata.html
 #[stable(feature = "metadata_ext", since = "1.1.0")]
 pub trait MetadataExt {
     /// Returns the ID of the device containing the file.
@@ -535,7 +522,7 @@ pub trait MetadataExt {
     fn atime(&self) -> i64;
     /// Returns the last access time of the file, in nanoseconds since [`atime`].
     ///
-    /// [`atime`]: #tymethod.atime
+    /// [`atime`]: MetadataExt::atime
     ///
     /// # Examples
     ///
@@ -571,7 +558,7 @@ pub trait MetadataExt {
     fn mtime(&self) -> i64;
     /// Returns the last modification time of the file, in nanoseconds since [`mtime`].
     ///
-    /// [`mtime`]: #tymethod.mtime
+    /// [`mtime`]: MetadataExt::mtime
     ///
     /// # Examples
     ///
@@ -607,7 +594,7 @@ pub trait MetadataExt {
     fn ctime(&self) -> i64;
     /// Returns the last status change time of the file, in nanoseconds since [`ctime`].
     ///
-    /// [`ctime`]: #tymethod.ctime
+    /// [`ctime`]: MetadataExt::ctime
     ///
     /// # Examples
     ///
@@ -714,12 +701,10 @@ impl MetadataExt for fs::Metadata {
     }
 }
 
-/// Unix-specific extensions for [`FileType`].
+/// Unix-specific extensions for [`fs::FileType`].
 ///
 /// Adds support for special Unix file types such as block/character devices,
 /// pipes, and sockets.
-///
-/// [`FileType`]: ../../../../std/fs/struct.FileType.html
 #[stable(feature = "file_type_ext", since = "1.5.0")]
 pub trait FileTypeExt {
     /// Returns `true` if this file type is a block device.
@@ -813,8 +798,6 @@ impl FileTypeExt for fs::FileType {
 }
 
 /// Unix-specific extension methods for [`fs::DirEntry`].
-///
-/// [`fs::DirEntry`]: ../../../../std/fs/struct.DirEntry.html
 #[stable(feature = "dir_entry_ext", since = "1.1.0")]
 pub trait DirEntryExt {
     /// Returns the underlying `d_ino` field in the contained `dirent`
@@ -875,8 +858,6 @@ pub fn symlink<P: AsRef<Path>, Q: AsRef<Path>>(src: P, dst: Q) -> io::Result<()>
 }
 
 /// Unix-specific extensions to [`fs::DirBuilder`].
-///
-/// [`fs::DirBuilder`]: ../../../../std/fs/struct.DirBuilder.html
 #[stable(feature = "dir_builder", since = "1.6.0")]
 pub trait DirBuilderExt {
     /// Sets the mode to create new directories with. This option defaults to