Fix doc nits

Many tiny changes to stdlib doc comments to make them consistent (for example
"Returns foo", rather than "Return foo", per RFC1574), adding missing periods, paragraph
breaks, backticks for monospace style, and other minor nits.

https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text

alloc/src/alloc.rs

@@ -57,7 +57,7 @@ pub struct Global;
 #[cfg(test)]
 pub use std::alloc::Global;
 
-/// Allocate memory with the global allocator.
+/// Allocates memory with the global allocator.
 ///
 /// This function forwards calls to the [`GlobalAlloc::alloc`] method
 /// of the allocator registered with the `#[global_allocator]` attribute
@@ -101,7 +101,7 @@ pub unsafe fn alloc(layout: Layout) -> *mut u8 {
     }
 }
 
-/// Deallocate memory with the global allocator.
+/// Deallocates memory with the global allocator.
 ///
 /// This function forwards calls to the [`GlobalAlloc::dealloc`] method
 /// of the allocator registered with the `#[global_allocator]` attribute
@@ -119,7 +119,7 @@ pub unsafe fn dealloc(ptr: *mut u8, layout: Layout) {
     unsafe { __rust_dealloc(ptr, layout.size(), layout.align()) }
 }
 
-/// Reallocate memory with the global allocator.
+/// Reallocates memory with the global allocator.
 ///
 /// This function forwards calls to the [`GlobalAlloc::realloc`] method
 /// of the allocator registered with the `#[global_allocator]` attribute
@@ -138,7 +138,7 @@ pub unsafe fn realloc(ptr: *mut u8, layout: Layout, new_size: usize) -> *mut u8
     unsafe { __rust_realloc(ptr, layout.size(), layout.align(), new_size) }
 }
 
-/// Allocate zero-initialized memory with the global allocator.
+/// Allocates zero-initialized memory with the global allocator.
 ///
 /// This function forwards calls to the [`GlobalAlloc::alloc_zeroed`] method
 /// of the allocator registered with the `#[global_allocator]` attribute
@@ -345,7 +345,7 @@ extern "Rust" {
     fn __rust_alloc_error_handler(size: usize, align: usize) -> !;
 }
 
-/// Signal a memory allocation error.
+/// Signals a memory allocation error.
 ///
 /// Callers of memory allocation APIs wishing to cease execution
 /// in response to an allocation error are encouraged to call this function,

alloc/src/boxed.rs

@@ -1268,9 +1268,11 @@ impl<T: ?Sized, A: Allocator> Box<T, A> {
     }
 
     /// Consumes and leaks the `Box`, returning a mutable reference,
-    /// `&'a mut T`. Note that the type `T` must outlive the chosen lifetime
-    /// `'a`. If the type has only static references, or none at all, then this
-    /// may be chosen to be `'static`.
+    /// `&'a mut T`.
+    ///
+    /// Note that the type `T` must outlive the chosen lifetime `'a`. If the type
+    /// has only static references, or none at all, then this may be chosen to be
+    /// `'static`.
     ///
     /// This function is mainly useful for data that lives for the remainder of
     /// the program's life. Dropping the returned reference will cause a memory
@@ -1853,7 +1855,7 @@ impl<T, const N: usize> TryFrom<Vec<T>> for Box<[T; N]> {
 }
 
 impl<A: Allocator> Box<dyn Any, A> {
-    /// Attempt to downcast the box to a concrete type.
+    /// Attempts to downcast the box to a concrete type.
     ///
     /// # Examples
     ///
@@ -1912,7 +1914,7 @@ impl<A: Allocator> Box<dyn Any, A> {
 }
 
 impl<A: Allocator> Box<dyn Any + Send, A> {
-    /// Attempt to downcast the box to a concrete type.
+    /// Attempts to downcast the box to a concrete type.
     ///
     /// # Examples
     ///
@@ -1971,7 +1973,7 @@ impl<A: Allocator> Box<dyn Any + Send, A> {
 }
 
 impl<A: Allocator> Box<dyn Any + Send + Sync, A> {
-    /// Attempt to downcast the box to a concrete type.
+    /// Attempts to downcast the box to a concrete type.
     ///
     /// # Examples
     ///

alloc/src/collections/binary_heap/mod.rs

@@ -965,6 +965,7 @@ impl<T, A: Allocator> BinaryHeap<T, A> {
     }
 
     /// Returns an iterator which retrieves elements in heap order.
+    ///
     /// This method consumes the original heap.
     ///
     /// # Examples
@@ -1361,7 +1362,7 @@ struct Hole<'a, T: 'a> {
 }
 
 impl<'a, T> Hole<'a, T> {
-    /// Create a new `Hole` at index `pos`.
+    /// Creates a new `Hole` at index `pos`.
     ///
     /// Unsafe because pos must be within the data slice.
     #[inline]

alloc/src/collections/btree/map/entry.rs

@@ -189,6 +189,7 @@ impl<'a, K: Ord, V, A: Allocator + Clone> Entry<'a, K, V, A> {
     }
 
     /// Ensures a value is in the entry by inserting, if empty, the result of the default function.
+    ///
     /// This method allows for generating key-derived values for insertion by providing the default
     /// function a reference to the key that was moved during the `.entry(key)` method call.
     ///

alloc/src/fmt.rs

@@ -600,8 +600,7 @@ pub use core::fmt::{LowerHex, Pointer, UpperHex};
 #[cfg(not(no_global_oom_handling))]
 use crate::string;
 
-/// The `format` function takes an [`Arguments`] struct and returns the resulting
-/// formatted string.
+/// Takes an [`Arguments`] struct and returns the resulting formatted string.
 ///
 /// The [`Arguments`] instance can be created with the [`format_args!`] macro.
 ///

alloc/src/raw_vec.rs

@@ -52,7 +52,7 @@ impl Cap {
 /// * Produces `Unique::dangling()` on zero-length allocations.
 /// * Avoids freeing `Unique::dangling()`.
 /// * Catches all overflows in capacity computations (promotes them to "capacity overflow" panics).
-/// * Guards against 32-bit systems allocating more than isize::MAX bytes.
+/// * Guards against 32-bit systems allocating more than `isize::MAX` bytes.
 /// * Guards against overflowing your length.
 /// * Calls `handle_alloc_error` for fallible allocations.
 /// * Contains a `ptr::Unique` and thus endows the user with all related benefits.
@@ -484,7 +484,7 @@ impl<T, A: Allocator> RawVec<T, A> {
 
         // `finish_grow` is non-generic over `T`.
         let ptr = finish_grow(new_layout, self.current_memory(), &mut self.alloc)?;
-        // SAFETY: finish_grow would have resulted in a capacity overflow if we tried to allocate more than isize::MAX items
+        // SAFETY: finish_grow would have resulted in a capacity overflow if we tried to allocate more than `isize::MAX` items
         unsafe { self.set_ptr_and_cap(ptr, cap) };
         Ok(())
     }
@@ -504,7 +504,7 @@ impl<T, A: Allocator> RawVec<T, A> {
 
         // `finish_grow` is non-generic over `T`.
         let ptr = finish_grow(new_layout, self.current_memory(), &mut self.alloc)?;
-        // SAFETY: finish_grow would have resulted in a capacity overflow if we tried to allocate more than isize::MAX items
+        // SAFETY: `finish_grow` would have resulted in a capacity overflow if we tried to allocate more than `isize::MAX` items
         unsafe {
             self.set_ptr_and_cap(ptr, cap);
         }

alloc/src/rc.rs

@@ -439,7 +439,7 @@ impl<T> Rc<T> {
     /// }
     ///
     /// impl Gadget {
-    ///     /// Construct a reference counted Gadget.
+    ///     /// Constructs a reference counted Gadget.
     ///     fn new() -> Rc<Self> {
     ///         // `me` is a `Weak<Gadget>` pointing at the new allocation of the
     ///         // `Rc` we're constructing.
@@ -449,7 +449,7 @@ impl<T> Rc<T> {
     ///         })
     ///     }
     ///
-    ///     /// Return a reference counted pointer to Self.
+    ///     /// Returns a reference counted pointer to Self.
     ///     fn me(&self) -> Rc<Self> {
     ///         self.me.upgrade().unwrap()
     ///     }
@@ -1900,7 +1900,7 @@ impl<T: Clone, A: Allocator> Rc<T, A> {
 }
 
 impl<A: Allocator> Rc<dyn Any, A> {
-    /// Attempt to downcast the `Rc<dyn Any>` to a concrete type.
+    /// Attempts to downcast the `Rc<dyn Any>` to a concrete type.
     ///
     /// # Examples
     ///
@@ -2586,7 +2586,7 @@ impl<T, const N: usize> From<[T; N]> for Rc<[T]> {
 #[cfg(not(no_global_oom_handling))]
 #[stable(feature = "shared_from_slice", since = "1.21.0")]
 impl<T: Clone> From<&[T]> for Rc<[T]> {
-    /// Allocate a reference-counted slice and fill it by cloning `v`'s items.
+    /// Allocates a reference-counted slice and fills it by cloning `v`'s items.
     ///
     /// # Example
     ///
@@ -2605,7 +2605,7 @@ impl<T: Clone> From<&[T]> for Rc<[T]> {
 #[cfg(not(no_global_oom_handling))]
 #[stable(feature = "shared_from_slice", since = "1.21.0")]
 impl From<&str> for Rc<str> {
-    /// Allocate a reference-counted string slice and copy `v` into it.
+    /// Allocates a reference-counted string slice and copies `v` into it.
     ///
     /// # Example
     ///
@@ -2624,7 +2624,7 @@ impl From<&str> for Rc<str> {
 #[cfg(not(no_global_oom_handling))]
 #[stable(feature = "shared_from_slice", since = "1.21.0")]
 impl From<String> for Rc<str> {
-    /// Allocate a reference-counted string slice and copy `v` into it.
+    /// Allocates a reference-counted string slice and copies `v` into it.
     ///
     /// # Example
     ///
@@ -2662,7 +2662,7 @@ impl<T: ?Sized, A: Allocator> From<Box<T, A>> for Rc<T, A> {
 #[cfg(not(no_global_oom_handling))]
 #[stable(feature = "shared_from_slice", since = "1.21.0")]
 impl<T, A: Allocator> From<Vec<T, A>> for Rc<[T], A> {
-    /// Allocate a reference-counted slice and move `v`'s items into it.
+    /// Allocates a reference-counted slice and moves `v`'s items into it.
     ///
     /// # Example
     ///
@@ -2695,8 +2695,8 @@ where
     B: ToOwned + ?Sized,
     Rc<B>: From<&'a B> + From<B::Owned>,
 {
-    /// Create a reference-counted pointer from
-    /// a clone-on-write pointer by copying its content.
+    /// Creates a reference-counted pointer from a clone-on-write pointer by
+    /// copying its content.
     ///
     /// # Example
     ///
@@ -3526,7 +3526,7 @@ impl<T: ?Sized, A: Allocator> AsRef<T> for Rc<T, A> {
 #[stable(feature = "pin", since = "1.33.0")]
 impl<T: ?Sized, A: Allocator> Unpin for Rc<T, A> {}
 
-/// Get the offset within an `RcBox` for the payload behind a pointer.
+/// Gets the offset within an `RcBox` for the payload behind a pointer.
 ///
 /// # Safety
 ///
@@ -3734,7 +3734,7 @@ struct UniqueRcUninit<T: ?Sized, A: Allocator> {
 
 #[cfg(not(no_global_oom_handling))]
 impl<T: ?Sized, A: Allocator> UniqueRcUninit<T, A> {
-    /// Allocate a RcBox with layout suitable to contain `for_value` or a clone of it.
+    /// Allocates a RcBox with layout suitable to contain `for_value` or a clone of it.
     fn new(for_value: &T, alloc: A) -> UniqueRcUninit<T, A> {
         let layout = Layout::for_value(for_value);
         let ptr = unsafe {

alloc/src/sync.rs

@@ -428,7 +428,7 @@ impl<T> Arc<T> {
     /// }
     ///
     /// impl Gadget {
-    ///     /// Construct a reference counted Gadget.
+    ///     /// Constructs a reference counted Gadget.
     ///     fn new() -> Arc<Self> {
     ///         // `me` is a `Weak<Gadget>` pointing at the new allocation of the
     ///         // `Arc` we're constructing.
@@ -438,7 +438,7 @@ impl<T> Arc<T> {
     ///         })
     ///     }
     ///
-    ///     /// Return a reference counted pointer to Self.
+    ///     /// Returns a reference counted pointer to Self.
     ///     fn me(&self) -> Arc<Self> {
     ///         self.me.upgrade().unwrap()
     ///     }
@@ -2531,7 +2531,7 @@ unsafe impl<#[may_dangle] T: ?Sized, A: Allocator> Drop for Arc<T, A> {
 }
 
 impl<A: Allocator> Arc<dyn Any + Send + Sync, A> {
-    /// Attempt to downcast the `Arc<dyn Any + Send + Sync>` to a concrete type.
+    /// Attempts to downcast the `Arc<dyn Any + Send + Sync>` to a concrete type.
     ///
     /// # Examples
     ///
@@ -3545,7 +3545,7 @@ impl<T, const N: usize> From<[T; N]> for Arc<[T]> {
 #[cfg(not(no_global_oom_handling))]
 #[stable(feature = "shared_from_slice", since = "1.21.0")]
 impl<T: Clone> From<&[T]> for Arc<[T]> {
-    /// Allocate a reference-counted slice and fill it by cloning `v`'s items.
+    /// Allocates a reference-counted slice and fills it by cloning `v`'s items.
     ///
     /// # Example
     ///
@@ -3564,7 +3564,7 @@ impl<T: Clone> From<&[T]> for Arc<[T]> {
 #[cfg(not(no_global_oom_handling))]
 #[stable(feature = "shared_from_slice", since = "1.21.0")]
 impl From<&str> for Arc<str> {
-    /// Allocate a reference-counted `str` and copy `v` into it.
+    /// Allocates a reference-counted `str` and copies `v` into it.
     ///
     /// # Example
     ///
@@ -3583,7 +3583,7 @@ impl From<&str> for Arc<str> {
 #[cfg(not(no_global_oom_handling))]
 #[stable(feature = "shared_from_slice", since = "1.21.0")]
 impl From<String> for Arc<str> {
-    /// Allocate a reference-counted `str` and copy `v` into it.
+    /// Allocates a reference-counted `str` and copies `v` into it.
     ///
     /// # Example
     ///
@@ -3621,7 +3621,7 @@ impl<T: ?Sized, A: Allocator> From<Box<T, A>> for Arc<T, A> {
 #[cfg(not(no_global_oom_handling))]
 #[stable(feature = "shared_from_slice", since = "1.21.0")]
 impl<T, A: Allocator + Clone> From<Vec<T, A>> for Arc<[T], A> {
-    /// Allocate a reference-counted slice and move `v`'s items into it.
+    /// Allocates a reference-counted slice and moves `v`'s items into it.
     ///
     /// # Example
     ///
@@ -3654,8 +3654,8 @@ where
     B: ToOwned + ?Sized,
     Arc<B>: From<&'a B> + From<B::Owned>,
 {
-    /// Create an atomically reference-counted pointer from
-    /// a clone-on-write pointer by copying its content.
+    /// Creates an atomically reference-counted pointer from a clone-on-write
+    /// pointer by copying its content.
     ///
     /// # Example
     ///
@@ -3811,7 +3811,7 @@ impl<T: ?Sized, A: Allocator> AsRef<T> for Arc<T, A> {
 #[stable(feature = "pin", since = "1.33.0")]
 impl<T: ?Sized, A: Allocator> Unpin for Arc<T, A> {}
 
-/// Get the offset within an `ArcInner` for the payload behind a pointer.
+/// Gets the offset within an `ArcInner` for the payload behind a pointer.
 ///
 /// # Safety
 ///
@@ -3833,7 +3833,7 @@ fn data_offset_align(align: usize) -> usize {
     layout.size() + layout.padding_needed_for(align)
 }
 
-/// A unique owning pointer to a [`ArcInner`] **that does not imply the contents are initialized,**
+/// A unique owning pointer to an [`ArcInner`] **that does not imply the contents are initialized,**
 /// but will deallocate it (without dropping the value) when dropped.
 ///
 /// This is a helper for [`Arc::make_mut()`] to ensure correct cleanup on panic.
@@ -3846,7 +3846,7 @@ struct UniqueArcUninit<T: ?Sized, A: Allocator> {
 
 #[cfg(not(no_global_oom_handling))]
 impl<T: ?Sized, A: Allocator> UniqueArcUninit<T, A> {
-    /// Allocate a ArcInner with layout suitable to contain `for_value` or a clone of it.
+    /// Allocates an ArcInner with layout suitable to contain `for_value` or a clone of it.
     fn new(for_value: &T, alloc: A) -> UniqueArcUninit<T, A> {
         let layout = Layout::for_value(for_value);
         let ptr = unsafe {

alloc/src/vec/into_iter.rs

@@ -114,8 +114,9 @@ impl<T, A: Allocator> IntoIter<T, A> {
     }
 
     /// Drops remaining elements and relinquishes the backing allocation.
-    /// This method guarantees it won't panic before relinquishing
-    /// the backing allocation.
+    ///
+    /// This method guarantees it won't panic before relinquishing the backing
+    /// allocation.
     ///
     /// This is roughly equivalent to the following, but more efficient
     ///