Rollup merge of #40682 - TigleyM:str_doc, r=steveklabnik

Update docs for std::str

fixes #29375

I noticed there are docs for the `str` primitive type, which contained extensive examples, so my additions give a more general explanation of `&str`. But please let me know if something can be explained more or changed.

r? @steveklabnik

1 files changed, 20 insertions, 1 deletions

diff --git a/src/libcollections/str.rs b/src/libcollections/str.rs
index 8abc9ca7e9f..219e818f7d7 100644
--- a/src/libcollections/str.rs
+++ b/src/libcollections/str.rs
@@ -10,9 +10,28 @@
 
 //! Unicode string slices.
 //!
+//! The `&str` type is one of the two main string types, the other being `String`.
+//! Unlike its `String` counterpart, its contents are borrowed.
+//!
+//! # Basic Usage
+//!
+//! A basic string declaration of `&str` type:
+//!
+//! ```
+//! let hello_world = "Hello, World!";
+//! ```
+//!
+//! Here we have declared a string literal, also known as a string slice.
+//! String literals have a static lifetime, which means the string `hello_world`
+//! is guaranteed to be valid for the duration of the entire program.
+//! We can explicitly specify `hello_world`'s lifetime as well:
+//!
+//! ```
+//! let hello_world: &'static str = "Hello, world!";
+//! ```
+//!
 //! *[See also the `str` primitive type](../../std/primitive.str.html).*
 
-
 #![stable(feature = "rust1", since = "1.0.0")]
 
 // Many of the usings in this module are only used in the test configuration.