From dbb058302388824b717816b42bbfbc00330fa36d Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Mon, 3 Aug 2020 01:01:52 +0100 Subject: [PATCH 1/5] docs: Reword `str::strip_prefix` and `strip_suffix` a bit "Some is returned with " is an awkward construction. The use of the passive voice is a bit odd, and doesn't seem like the house style. So say instead "returns X, wrapped in `Some`", for which there is some other precedent in stdlib. Instead of repeating "with the prefix removed", say "after the prefix". This is a bit clearer that the original is not modified. Signed-off-by: Ian Jackson --- library/core/src/str/mod.rs | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/library/core/src/str/mod.rs b/library/core/src/str/mod.rs index 3e18a4e70627d..e6c37b6ba5986 100644 --- a/library/core/src/str/mod.rs +++ b/library/core/src/str/mod.rs @@ -1964,11 +1964,12 @@ impl str { /// Returns a string slice with the prefix removed. /// - /// If the string starts with the pattern `prefix`, `Some` is returned with the substring where - /// the prefix is removed. Unlike `trim_start_matches`, this method removes the prefix exactly - /// once. + /// If the string starts with the pattern `prefix`, returns + /// substring after the prefix, wrapped in `Some`. + /// Unlike `trim_start_matches`, this method removes the + /// prefix exactly once. /// - /// If the string does not start with `prefix`, `None` is returned. + /// If the string does not start with `prefix`, returns `None`. /// /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a /// function or closure that determines if a character matches. @@ -1992,11 +1993,12 @@ impl str { /// Returns a string slice with the suffix removed. /// - /// If the string ends with the pattern `suffix`, `Some` is returned with the substring where - /// the suffix is removed. Unlike `trim_end_matches`, this method removes the suffix exactly - /// once. + /// If the string ends with the pattern `suffix`, returns the + /// substring before the suffix, wrapped in `Some`. + /// Unlike `trim_end_matches`, this method removes the + /// suffix exactly once. /// - /// If the string does not end with `suffix`, `None` is returned. + /// If the string does not end with `suffix`, returns `None`. /// /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a /// function or closure that determines if a character matches. From b7974bd3cd2df94d19dad467fa09a79f78067559 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Mon, 3 Aug 2020 01:06:11 +0100 Subject: [PATCH 2/5] docs: Reword `slice::strip_prefix` and `strip_suffix` a bit The stabilisation issue, #73413, has an open item for documentation. I looked at the docs and it is all there, but I felt it could do with some minor wording improvement. I looked at the `str::strip_prefix` docs for a template. (That resulted in me slightly changing that doc too.) I de-linkified `None` and `Some`, as I felt that rather noisy.. I searched stdlib, and these don't seem to be usually linkified. Signed-off-by: Ian Jackson --- library/core/src/slice/mod.rs | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/library/core/src/slice/mod.rs b/library/core/src/slice/mod.rs index d0d88c01f5b2c..1dfe899d3e5c7 100644 --- a/library/core/src/slice/mod.rs +++ b/library/core/src/slice/mod.rs @@ -1703,8 +1703,12 @@ impl [T] { /// Returns a subslice with the prefix removed. /// - /// This method returns [`None`] if slice does not start with `prefix`. - /// Also it returns the original slice if `prefix` is an empty slice. + /// If the slice starts with `prefix`, returns + /// the subslice after the prefix, wrapped in `Some`. + /// + /// If the slice does not start with `prefix`, returns `None`. + /// + /// (If `prefix` is empty, simply returns the original slice.) /// /// # Examples /// @@ -1734,8 +1738,12 @@ impl [T] { /// Returns a subslice with the suffix removed. /// - /// This method returns [`None`] if slice does not end with `suffix`. - /// Also it returns the original slice if `suffix` is an empty slice + /// If the slice ends with `suffix`, returns + /// the subslice before the suffix, wrapped in `Some`. + /// + /// If the slice does not end with `suffix`, returns `None`. + /// + /// (If `suffix` is empty, simply returns the original slice.) /// /// # Examples /// From 4549c777e690c69552dea2f2ea04c56074430546 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Mon, 12 Oct 2020 12:40:12 +0100 Subject: [PATCH 3/5] docs: Rewrap `str::strip_prefix` and `strip_suffix` back to 100 Requested-by: @LukasKalbertodt Signed-off-by: Ian Jackson --- library/core/src/str/mod.rs | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/library/core/src/str/mod.rs b/library/core/src/str/mod.rs index e6c37b6ba5986..a76c8997a1063 100644 --- a/library/core/src/str/mod.rs +++ b/library/core/src/str/mod.rs @@ -1964,10 +1964,8 @@ impl str { /// Returns a string slice with the prefix removed. /// - /// If the string starts with the pattern `prefix`, returns - /// substring after the prefix, wrapped in `Some`. - /// Unlike `trim_start_matches`, this method removes the - /// prefix exactly once. + /// If the string starts with the pattern `prefix`, returns substring after the prefix, wrapped + /// in `Some`. Unlike `trim_start_matches`, this method removes the prefix exactly once. /// /// If the string does not start with `prefix`, returns `None`. /// @@ -1993,10 +1991,8 @@ impl str { /// Returns a string slice with the suffix removed. /// - /// If the string ends with the pattern `suffix`, returns the - /// substring before the suffix, wrapped in `Some`. - /// Unlike `trim_end_matches`, this method removes the - /// suffix exactly once. + /// If the string ends with the pattern `suffix`, returns the substring before the suffix, + /// wrapped in `Some`. Unlike `trim_end_matches`, this method removes the suffix exactly once. /// /// If the string does not end with `suffix`, returns `None`. /// From 6f5e96fb5fcd7fb6c67c61027615abd96a9e5e69 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Mon, 12 Oct 2020 12:45:05 +0100 Subject: [PATCH 4/5] docs: Rewrap `slice::strip_prefix` and `strip_suffix` back to 100 Requested-by: @LukasKalbertodt Signed-off-by: Ian Jackson --- library/core/src/slice/mod.rs | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/library/core/src/slice/mod.rs b/library/core/src/slice/mod.rs index 1dfe899d3e5c7..1282bb54f00d5 100644 --- a/library/core/src/slice/mod.rs +++ b/library/core/src/slice/mod.rs @@ -1703,8 +1703,7 @@ impl [T] { /// Returns a subslice with the prefix removed. /// - /// If the slice starts with `prefix`, returns - /// the subslice after the prefix, wrapped in `Some`. + /// If the slice starts with `prefix`, returns the subslice after the prefix, wrapped in `Some`. /// /// If the slice does not start with `prefix`, returns `None`. /// @@ -1738,8 +1737,7 @@ impl [T] { /// Returns a subslice with the suffix removed. /// - /// If the slice ends with `suffix`, returns - /// the subslice before the suffix, wrapped in `Some`. + /// If the slice ends with `suffix`, returns the subslice before the suffix, wrapped in `Some`. /// /// If the slice does not end with `suffix`, returns `None`. /// From 22358c650ba72e29a35076e243d84d47915ff35c Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Mon, 12 Oct 2020 12:46:17 +0100 Subject: [PATCH 5/5] docs: `slice::strip_prefix` and `strip_suffix`, fold in sentence Roughly as requested by @LukasKalbertodt. I still prefer clearly making these two cases. Signed-off-by: Ian Jackson --- library/core/src/slice/mod.rs | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/library/core/src/slice/mod.rs b/library/core/src/slice/mod.rs index 1282bb54f00d5..4c425ea8da94f 100644 --- a/library/core/src/slice/mod.rs +++ b/library/core/src/slice/mod.rs @@ -1704,11 +1704,10 @@ impl [T] { /// Returns a subslice with the prefix removed. /// /// If the slice starts with `prefix`, returns the subslice after the prefix, wrapped in `Some`. + /// If `prefix` is empty, simply returns the original slice. /// /// If the slice does not start with `prefix`, returns `None`. /// - /// (If `prefix` is empty, simply returns the original slice.) - /// /// # Examples /// /// ``` @@ -1738,11 +1737,10 @@ impl [T] { /// Returns a subslice with the suffix removed. /// /// If the slice ends with `suffix`, returns the subslice before the suffix, wrapped in `Some`. + /// If `suffix` is empty, simply returns the original slice. /// /// If the slice does not end with `suffix`, returns `None`. /// - /// (If `suffix` is empty, simply returns the original slice.) - /// /// # Examples /// /// ```