Update documentation for indexing/slicing methods

See #39911

2 files changed, 23 insertions, 2 deletions

diff --git a/src/libcollections/slice.rs b/src/libcollections/slice.rs
index 5696f5fe6a7..233ff8a5154 100644
--- a/src/libcollections/slice.rs
+++ b/src/libcollections/slice.rs
@@ -393,7 +393,12 @@ impl<T> [T] {
     }
 
     /// Returns a reference to an element or subslice, without doing bounds
-    /// checking. So use it very carefully!
+    /// checking.
+    ///
+    /// This is generally not recommended, use with caution! For a safe
+    /// alternative see [`get`].
+    ///
+    /// [`get`]: #method.get
     ///
     /// # Examples
     ///
@@ -413,7 +418,12 @@ impl<T> [T] {
     }
 
     /// Returns a mutable reference to an element or subslice, without doing
-    /// bounds checking. So use it very carefully!
+    /// bounds checking.
+    ///
+    /// This is generally not recommended, use with caution! For a safe
+    /// alternative see [`get_mut`].
+    ///
+    /// [`get_mut`]: #method.get_mut
     ///
     /// # Examples
     ///
diff --git a/src/libcollections/str.rs b/src/libcollections/str.rs
index 7e67befb700..1a3e665a044 100644
--- a/src/libcollections/str.rs
+++ b/src/libcollections/str.rs
@@ -435,6 +435,12 @@ 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 [`Index`].
+    ///
+    /// [`str`]: primitive.str.html
+    /// [`Index`]: ops/trait.Index.html
+    ///
     /// This new slice goes from `begin` to `end`, including `begin` but
     /// excluding `end`.
     ///
@@ -477,6 +483,11 @@ 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`].
+    ///
+    /// [`str`]: primitive.str.html
+    /// [`IndexMut`]: ops/trait.IndexMut.html
     ///
     /// This new slice goes from `begin` to `end`, including `begin` but
     /// excluding `end`.