rust-lang/rust
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Fix doc nits

Browse Source 
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
This commit is contained in:
John Arundel
2024-07-15 12:26:30 +01:00
parent 83d67685ac
commit a19472a93e
146 changed files with 808 additions and 738 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
library/core/src/str/mod.rs
View File

@@ -592,6 +592,7 @@ impl str {
/// Creates a string slice from another string slice, bypassing safety
/// checks.
///
/// This is generally not recommended, use with caution! For a safe
/// alternative see [`str`] and [`IndexMut`].
///
@@ -623,7 +624,7 @@ impl str {
unsafe { &mut *(begin..end).get_unchecked_mut(self) }
}
/// Divide one string slice into two at an index.
/// Divides one string slice into two at an index.
///
/// The argument, `mid`, should be a byte offset from the start of the
/// string. It must also be on the boundary of a UTF-8 code point.
@@ -662,7 +663,7 @@ impl str {
}
}
/// Divide one mutable string slice into two at an index.
/// Divides one mutable string slice into two at an index.
///
/// The argument, `mid`, should be a byte offset from the start of the
/// string. It must also be on the boundary of a UTF-8 code point.
@@ -705,7 +706,7 @@ impl str {
}
}
/// Divide one string slice into two at an index.
/// Divides one string slice into two at an index.
///
/// The argument, `mid`, should be a valid byte offset from the start of the
/// string. It must also be on the boundary of a UTF-8 code point. The
@@ -744,7 +745,7 @@ impl str {
}
}
/// Divide one mutable string slice into two at an index.
/// Divides one mutable string slice into two at an index.
///
/// The argument, `mid`, should be a valid byte offset from the start of the
/// string. It must also be on the boundary of a UTF-8 code point. The
@@ -784,7 +785,7 @@ impl str {
}
}
/// Divide one string slice into two at an index.
/// Divides one string slice into two at an index.
///
/// # Safety
///
@@ -912,7 +913,7 @@ impl str {
CharIndices { front_offset: 0, iter: self.chars() }
}
/// An iterator over the bytes of a string slice.
/// Returns an iterator over the bytes of a string slice.
///
/// As a string slice consists of a sequence of bytes, we can iterate
/// through a string slice by byte. This method returns such an iterator.
@@ -1038,7 +1039,7 @@ impl str {
SplitAsciiWhitespace { inner }
}
/// An iterator over the lines of a string, as string slices.
/// Returns an iterator over the lines of a string, as string slices.
///
/// Lines are split at line endings that are either newlines (`\n`) or
/// sequences of a carriage return followed by a line feed (`\r\n`).
@@ -1089,7 +1090,7 @@ impl str {
Lines(self.split_inclusive('\n').map(LinesMap))
}
/// An iterator over the lines of a string.
/// Returns an iterator over the lines of a string.
#[stable(feature = "rust1", since = "1.0.0")]
#[deprecated(since = "1.4.0", note = "use lines() instead now", suggestion = "lines")]
#[inline]
@@ -1303,7 +1304,7 @@ impl str {
pat.into_searcher(self).next_match_back().map(|(i, _)| i)
}
/// An iterator over substrings of this string slice, separated by
/// Returns an iterator over substrings of this string slice, separated by
/// characters matched by a pattern.
///
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
@@ -1428,10 +1429,11 @@ impl str {
})
}
/// An iterator over substrings of this string slice, separated by
/// characters matched by a pattern. Differs from the iterator produced by
/// `split` in that `split_inclusive` leaves the matched part as the
/// terminator of the substring.
/// Returns an iterator over substrings of this string slice, separated by
/// characters matched by a pattern.
///
/// Differs from the iterator produced by `split` in that `split_inclusive`
/// leaves the matched part as the terminator of the substring.
///
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
/// function or closure that determines if a character matches.
@@ -1468,8 +1470,8 @@ impl str {
})
}
/// An iterator over substrings of the given string slice, separated by
/// characters matched by a pattern and yielded in reverse order.
/// Returns an iterator over substrings of the given string slice, separated
/// by characters matched by a pattern and yielded in reverse order.
///
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
/// function or closure that determines if a character matches.
@@ -1520,8 +1522,8 @@ impl str {
RSplit(self.split(pat).0)
}
/// An iterator over substrings of the given string slice, separated by
/// characters matched by a pattern.
/// Returns an iterator over substrings of the given string slice, separated
/// by characters matched by a pattern.
///
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
/// function or closure that determines if a character matches.
@@ -1566,7 +1568,7 @@ impl str {
SplitTerminator(SplitInternal { allow_trailing_empty: false, ..self.split(pat).0 })
}
/// An iterator over substrings of `self`, separated by characters
/// Returns an iterator over substrings of `self`, separated by characters
/// matched by a pattern and yielded in reverse order.
///
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
@@ -1615,8 +1617,8 @@ impl str {
RSplitTerminator(self.split_terminator(pat).0)
}
/// An iterator over substrings of the given string slice, separated by a
/// pattern, restricted to returning at most `n` items.
/// Returns an iterator over substrings of the given string slice, separated
/// by a pattern, restricted to returning at most `n` items.
///
/// If `n` substrings are returned, the last substring (the `n`th substring)
/// will contain the remainder of the string.
@@ -1667,9 +1669,9 @@ impl str {
SplitN(SplitNInternal { iter: self.split(pat).0, count: n })
}
/// An iterator over substrings of this string slice, separated by a
/// pattern, starting from the end of the string, restricted to returning
/// at most `n` items.
/// Returns an iterator over substrings of this string slice, separated by a
/// pattern, starting from the end of the string, restricted to returning at
/// most `n` items.
///
/// If `n` substrings are returned, the last substring (the `n`th substring)
/// will contain the remainder of the string.
@@ -1759,8 +1761,8 @@ impl str {
unsafe { Some((self.get_unchecked(..start), self.get_unchecked(end..))) }
}
/// An iterator over the disjoint matches of a pattern within the given string
/// slice.
/// Returns an iterator over the disjoint matches of a pattern within the
/// given string slice.
///
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
/// function or closure that determines if a character matches.
@@ -1794,8 +1796,8 @@ impl str {
Matches(MatchesInternal(pat.into_searcher(self)))
}
/// An iterator over the disjoint matches of a pattern within this string slice,
/// yielded in reverse order.
/// Returns an iterator over the disjoint matches of a pattern within this
/// string slice, yielded in reverse order.
///
/// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
/// function or closure that determines if a character matches.
@@ -1831,7 +1833,7 @@ impl str {
RMatches(self.matches(pat).0)
}
/// An iterator over the disjoint matches of a pattern within this string
/// Returns an iterator over the disjoint matches of a pattern within this string
/// slice as well as the index that the match starts at.
///
/// For matches of `pat` within `self` that overlap, only the indices
@@ -1872,7 +1874,7 @@ impl str {
MatchIndices(MatchIndicesInternal(pat.into_searcher(self)))
}
/// An iterator over the disjoint matches of a pattern within `self`,
/// Returns an iterator over the disjoint matches of a pattern within `self`,
/// yielded in reverse order along with the index of the match.
///
/// For matches of `pat` within `self` that overlap, only the indices
@@ -2597,7 +2599,7 @@ impl str {
unsafe { core::str::from_utf8_unchecked(self.as_bytes().trim_ascii()) }
}
/// Return an iterator that escapes each char in `self` with [`char::escape_debug`].
/// Returns an iterator that escapes each char in `self` with [`char::escape_debug`].
///
/// Note: only extended grapheme codepoints that begin the string will be
/// escaped.
@@ -2646,7 +2648,7 @@ impl str {
}
}
/// Return an iterator that escapes each char in `self` with [`char::escape_default`].
/// Returns an iterator that escapes each char in `self` with [`char::escape_default`].
///
/// # Examples
///
@@ -2684,7 +2686,7 @@ impl str {
EscapeDefault { inner: self.chars().flat_map(CharEscapeDefault) }
}
/// Return an iterator that escapes each char in `self` with [`char::escape_unicode`].
/// Returns an iterator that escapes each char in `self` with [`char::escape_unicode`].
///
/// # Examples
///