From 4ca315156805d951663e66c13f395d7f405c9ed2 Mon Sep 17 00:00:00 2001
From: Jani Mustonen <janijohannes@kapsi.fi>
Date: Sun, 31 Mar 2024 16:05:34 +0300
Subject: [PATCH] doc: describe panic conditions for SliceIndex implementations

Implementation note: The most probable place for users to find
the documentation is at https://doc.rust-lang.org/std/slice/trait.SliceIndex.html

On that page, documentation added to specific methods will not
be visible. As such, I opted to add the comments to the impl blocks
directly.

Helps with #121568.
---
 library/core/src/slice/index.rs | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/library/core/src/slice/index.rs b/library/core/src/slice/index.rs
index 127a407dae5..8d7b6165510 100644
--- a/library/core/src/slice/index.rs
+++ b/library/core/src/slice/index.rs
@@ -195,6 +195,7 @@ pub unsafe trait SliceIndex<T: ?Sized>: private_slice_index::Sealed {
     fn index_mut(self, slice: &mut T) -> &mut Self::Output;
 }
 
+/// The methods `index` and `index_mut` panic if the index is out of bounds.
 #[stable(feature = "slice_get_slice_impls", since = "1.15.0")]
 #[rustc_const_unstable(feature = "const_slice_index", issue = "none")]
 unsafe impl<T> SliceIndex<[T]> for usize {
@@ -328,6 +329,9 @@ fn index_mut(self, slice: &mut [T]) -> &mut [T] {
     }
 }
 
+/// The methods `index` and `index_mut` panic if:
+/// - the start of the range is greater than the end of the range or
+/// - the end of the range is out of bounds.
 #[stable(feature = "slice_get_slice_impls", since = "1.15.0")]
 #[rustc_const_unstable(feature = "const_slice_index", issue = "none")]
 unsafe impl<T> SliceIndex<[T]> for ops::Range<usize> {
@@ -416,6 +420,7 @@ fn index_mut(self, slice: &mut [T]) -> &mut [T] {
     }
 }
 
+/// The methods `index` and `index_mut` panic if the end of the range is out of bounds.
 #[stable(feature = "slice_get_slice_impls", since = "1.15.0")]
 #[rustc_const_unstable(feature = "const_slice_index", issue = "none")]
 unsafe impl<T> SliceIndex<[T]> for ops::RangeTo<usize> {
@@ -454,6 +459,7 @@ fn index_mut(self, slice: &mut [T]) -> &mut [T] {
     }
 }
 
+/// The methods `index` and `index_mut` panic if the start of the range is out of bounds.
 #[stable(feature = "slice_get_slice_impls", since = "1.15.0")]
 #[rustc_const_unstable(feature = "const_slice_index", issue = "none")]
 unsafe impl<T> SliceIndex<[T]> for ops::RangeFrom<usize> {
@@ -536,6 +542,10 @@ fn index_mut(self, slice: &mut [T]) -> &mut [T] {
     }
 }
 
+/// The methods `index` and `index_mut` panic if:
+/// - the end of the range is `usize::MAX` or
+/// - the start of the range is greater than the end of the range or
+/// - the end of the range is out of bounds.
 #[stable(feature = "inclusive_range", since = "1.26.0")]
 #[rustc_const_unstable(feature = "const_slice_index", issue = "none")]
 unsafe impl<T> SliceIndex<[T]> for ops::RangeInclusive<usize> {
@@ -580,6 +590,7 @@ fn index_mut(self, slice: &mut [T]) -> &mut [T] {
     }
 }
 
+/// The methods `index` and `index_mut` panic if the end of the range is out of bounds.
 #[stable(feature = "inclusive_range", since = "1.26.0")]
 #[rustc_const_unstable(feature = "const_slice_index", issue = "none")]
 unsafe impl<T> SliceIndex<[T]> for ops::RangeToInclusive<usize> {