docs: Expand on deprecation instructions

clap_complete/src/shells/shell.rs

@@ -24,7 +24,15 @@ pub enum Shell {
 
 impl Shell {
     /// Deprecated, replaced with [`EnumValueParser`][clap::builder::EnumValueParser]
-    #[deprecated(since = "3.2.0", note = "Replaced with `EnumValueParser`")]
+    ///
+    /// Builder API: Instead of `arg.possible_values(Shell::possible_values())`, use `arg.value_parser(value_parser!(Shell))`
+    #[deprecated(
+        since = "3.2.0",
+        note = "Replaced with `EnumValueParser`
+
+Builder API: Instead of `arg.possible_values(Shell::possible_values())`, use `arg.value_parser(value_parser!(Shell))`
+"
+    )]
     pub fn possible_values() -> impl Iterator<Item = PossibleValue<'static>> {
         Shell::value_variants()
             .iter()

clap_derive/src/derives/args.rs

@@ -302,7 +302,7 @@ pub fn gen_augment(
                         parse_try_from_os_str();
                     },
                     ParserKind::FromFlag => quote_spanned! { func.span()=>
-                        #[deprecated(since = "3.2.0", note = "Replaced with `#[clap(action = ArgAction::SetTrue)]`")]
+                        #[deprecated(since = "3.2.0", note = "Replaced with `#[clap(action = ArgAction::SetTrue, default_value = <absent>, default_missing_value = <present>)]`")]
                         fn parse_from_flag() {
                         }
                         parse_from_flag();

src/builder/action.rs

@@ -71,11 +71,24 @@ pub enum ArgAction {
     /// ```
     Append,
     /// Deprecated, replaced with [`ArgAction::Set`] or [`ArgAction::Append`]
+    ///
+    /// Builder: Instead of `arg.action(ArgAction::StoreValue)`,
+    /// - Use `arg.action(ArgAction::Set)` for single-occurrence arguments
+    /// - Use `arg.action(ArgAction::Append)` for multiple-occurrence arguments
+    ///
+    /// Derive: opt-in to the new behavior with `#[clap(action)]`
     #[cfg_attr(
         feature = "deprecated",
         deprecated(
             since = "3.2.0",
-            note = "Replaced with `ArgAction::Set` or `ArgAction::Append`"
+            note = "Replaced with `ArgAction::Set` or `ArgAction::Append`
+
+Derive: opt-in to the new behavior with `#[clap(action)]`
+
+Builder: Instead of `arg.action(ArgAction::StoreValue)`,
+- Use `arg.action(ArgAction::Set)` for single-occurrence arguments
+- Use `arg.action(ArgAction::Append)` for multiple-occurrence arguments
+"
         )
     )]
     StoreValue,
@@ -84,7 +97,14 @@ pub enum ArgAction {
         feature = "deprecated",
         deprecated(
             since = "3.2.0",
-            note = "Replaced with `ArgAction::SetTrue` or `ArgAction::Count`"
+            note = "Replaced with `ArgAction::SetTrue` or `ArgAction::Count`
+
+Derive: opt-in to the new behavior with `#[clap(action)]`
+
+Builder: Instead of `arg.action(ArgAction::IncOccurrence)`,
+- Use `arg.action(ArgAction::SetTrue)` if you just care if its set, then switch `matches.is_present` to `matches.get_flag`
+- Use `arg.action(ArgAction::Count)` if you care how many times its set, then switch `matches.occurrences_of` to `matches.get_count`
+"
         )
     )]
     IncOccurrence,