From 0fa90b3813be124d7ce96ae0cbe88e2209462445 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Wed, 14 Dec 2022 19:21:03 -0600
Subject: [PATCH] docs: Clarify role of Resettable

Inspired by #4554
---
 src/builder/resettable.rs | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/src/builder/resettable.rs b/src/builder/resettable.rs
index 0176d3984544..1cde72ea71b4 100644
--- a/src/builder/resettable.rs
+++ b/src/builder/resettable.rs
@@ -10,6 +10,24 @@ use crate::builder::ValueParser;
 use crate::builder::ValueRange;
 
 /// Clearable builder value
+///
+/// This allows a builder function to both accept any value that can [`Into::into`] `T` (like
+/// `&str` into `OsStr`) as well as `None` to reset it to the default.  This is needed to
+/// workaround a limitation where you can't have a function argument that is `impl Into<Option<T>>`
+/// where `T` is `impl Into<S>` accept `None` as its type is ambiguous.
+///
+/// # Example
+///
+/// ```rust
+/// # use clap::Command;
+/// # use clap::Arg;
+/// fn common() -> Command {
+///     Command::new("cli")
+///         .arg(Arg::new("input").short('i').long("input"))
+/// }
+/// let mut command = cli();
+/// command.mut_arg("input", |arg| arg.short(None));
+/// ```
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum Resettable<T> {
     /// Overwrite builder value