add modify-in-place methods to option overview

1 files changed, 29 insertions, 0 deletions

diff --git a/library/core/src/option.rs b/library/core/src/option.rs
index c1b9517658a..dea32872243 100644
--- a/library/core/src/option.rs
+++ b/library/core/src/option.rs
@@ -296,6 +296,35 @@
 //! }
 //! ```
 //!
+//! ## Modifying an [`Option`] in-place
+//!
+//! These methods return a mutable reference to the contained value of a
+//! [`Some`].
+//!
+//! * [`insert`] inserts a value, dropping any old contents
+//! * [`get_or_insert`] gets the current value, inserting a provided
+//!   default value if it is [`None`]
+//! * [`get_or_insert_default`] gets the current value, inserting the
+//!   default value of type `T` if it is [`None`]
+//! * [`get_or_insert_with`] gets the current value, inserting a default
+//!   computed by the provided function if it is [`None`]
+//!
+//! [`insert`]: Option::insert
+//! [`get_or_insert`]: Option::get_or_insert
+//! [`get_or_insert_default`]: Option::get_or_insert_default
+//! [`get_or_insert_with`]: Option::get_or_insert_with
+//!
+//! These methods transfer ownership of the [`Option`].
+//!
+//! * [`take`] takes ownership of the [`Option`], including any contained
+//!   value, replacing it with [`None`]
+//! * [`replace`] takes ownership of the [`Option`], including any
+//!   contained value, replacing it with a [`Some`] containing the provided
+//!   value
+//!
+//! [`take`]: Option::take
+//! [`replace`]: Option::replace
+//!
 //! # Examples
 //!
 //! Basic pattern matching on [`Option`]: