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

2 files changed, 17 insertions, 14 deletions

diff --git a/library/alloc/src/vec/into_iter.rs b/library/alloc/src/vec/into_iter.rs
index 10f62e4bb62..c3a8660383d 100644
--- a/library/alloc/src/vec/into_iter.rs
+++ b/library/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
     ///
diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs
index 729d5dd4fe4..49b89d67023 100644
--- a/library/alloc/src/vec/mod.rs
+++ b/library/alloc/src/vec/mod.rs
@@ -2373,9 +2373,11 @@ impl<T, A: Allocator> Vec<T, A> {
     }
 
     /// Consumes and leaks the `Vec`, returning a mutable reference to the contents,
-    /// `&'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`.
     ///
     /// As of Rust 1.57, this method does not reallocate or shrink the `Vec`,
     /// so the leaked allocation may include unused capacity that is not part
@@ -3359,7 +3361,7 @@ impl<T, A: Allocator> AsMut<[T]> for Vec<T, A> {
 #[cfg(not(no_global_oom_handling))]
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: Clone> From<&[T]> for Vec<T> {
-    /// Allocate a `Vec<T>` and fill it by cloning `s`'s items.
+    /// Allocates a `Vec<T>` and fills it by cloning `s`'s items.
     ///
     /// # Examples
     ///
@@ -3379,7 +3381,7 @@ impl<T: Clone> From<&[T]> for Vec<T> {
 #[cfg(not(no_global_oom_handling))]
 #[stable(feature = "vec_from_mut", since = "1.19.0")]
 impl<T: Clone> From<&mut [T]> for Vec<T> {
-    /// Allocate a `Vec<T>` and fill it by cloning `s`'s items.
+    /// Allocates a `Vec<T>` and fills it by cloning `s`'s items.
     ///
     /// # Examples
     ///
@@ -3399,7 +3401,7 @@ impl<T: Clone> From<&mut [T]> for Vec<T> {
 #[cfg(not(no_global_oom_handling))]
 #[stable(feature = "vec_from_array_ref", since = "1.74.0")]
 impl<T: Clone, const N: usize> From<&[T; N]> for Vec<T> {
-    /// Allocate a `Vec<T>` and fill it by cloning `s`'s items.
+    /// Allocates a `Vec<T>` and fills it by cloning `s`'s items.
     ///
     /// # Examples
     ///
@@ -3414,7 +3416,7 @@ impl<T: Clone, const N: usize> From<&[T; N]> for Vec<T> {
 #[cfg(not(no_global_oom_handling))]
 #[stable(feature = "vec_from_array_ref", since = "1.74.0")]
 impl<T: Clone, const N: usize> From<&mut [T; N]> for Vec<T> {
-    /// Allocate a `Vec<T>` and fill it by cloning `s`'s items.
+    /// Allocates a `Vec<T>` and fills it by cloning `s`'s items.
     ///
     /// # Examples
     ///
@@ -3429,7 +3431,7 @@ impl<T: Clone, const N: usize> From<&mut [T; N]> for Vec<T> {
 #[cfg(not(no_global_oom_handling))]
 #[stable(feature = "vec_from_array", since = "1.44.0")]
 impl<T, const N: usize> From<[T; N]> for Vec<T> {
-    /// Allocate a `Vec<T>` and move `s`'s items into it.
+    /// Allocates a `Vec<T>` and moves `s`'s items into it.
     ///
     /// # Examples
     ///
@@ -3452,7 +3454,7 @@ impl<'a, T> From<Cow<'a, [T]>> for Vec<T>
 where
     [T]: ToOwned<Owned = Vec<T>>,
 {
-    /// Convert a clone-on-write slice into a vector.
+    /// Converts a clone-on-write slice into a vector.
     ///
     /// If `s` already owns a `Vec<T>`, it will be returned directly.
     /// If `s` is borrowing a slice, a new `Vec<T>` will be allocated and
@@ -3475,7 +3477,7 @@ where
 #[cfg(not(test))]
 #[stable(feature = "vec_from_box", since = "1.18.0")]
 impl<T, A: Allocator> From<Box<[T], A>> for Vec<T, A> {
-    /// Convert a boxed slice into a vector by transferring ownership of
+    /// Converts a boxed slice into a vector by transferring ownership of
     /// the existing heap allocation.
     ///
     /// # Examples
@@ -3494,7 +3496,7 @@ impl<T, A: Allocator> From<Box<[T], A>> for Vec<T, A> {
 #[cfg(not(test))]
 #[stable(feature = "box_from_vec", since = "1.20.0")]
 impl<T, A: Allocator> From<Vec<T, A>> for Box<[T], A> {
-    /// Convert a vector into a boxed slice.
+    /// Converts a vector into a boxed slice.
     ///
     /// Before doing the conversion, this method discards excess capacity like [`Vec::shrink_to_fit`].
     ///
@@ -3522,7 +3524,7 @@ impl<T, A: Allocator> From<Vec<T, A>> for Box<[T], A> {
 #[cfg(not(no_global_oom_handling))]
 #[stable(feature = "rust1", since = "1.0.0")]
 impl From<&str> for Vec<u8> {
-    /// Allocate a `Vec<u8>` and fill it with a UTF-8 string.
+    /// Allocates a `Vec<u8>` and fills it with a UTF-8 string.
     ///
     /// # Examples
     ///