From 22b3b42a4cc03edd089edb3545b65f593d4b7145 Mon Sep 17 00:00:00 2001
From: Yeming Liu <11371776+isra-fel@users.noreply.github.com>
Date: Fri, 17 Oct 2025 00:43:09 +0000
Subject: [PATCH] rewrite shouldprocess suppression doc

---
 docs/directives.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/docs/directives.md b/docs/directives.md
index 1d9d0d79de3..c4d49693de4 100644
--- a/docs/directives.md
+++ b/docs/directives.md
@@ -90,6 +90,7 @@ The following directives cover the most common tweaking scenarios for cmdlet gen
 - [Cmdlet Rename](#Cmdlet-Rename)
 - [Cmdlet Aliasing](#Cmdlet-Aliasing)
 - [Cmdlet Suppression (Removal and Hiding)](#Cmdlet-Suppression)
+- [Suppress ShouldProcess (-WhatIf / -Confirm)](#Suppress-ShouldProcess)
 - [Parameter Rename](#Parameter-Rename)
 - [Parameter Aliasing](#Parameter-Aliasing)
 - [Parameter Hiding](#Parameter-Hiding)
@@ -209,6 +210,43 @@ directive:
     remove: true
 ```
 
+### Suppress ShouldProcess
+Some generated cmdlets include PowerShell `SupportsShouldProcess` semantics, exposing `-WhatIf` and `-Confirm`. This is appropriate for operations that can change state. However, certain service operations use non-GET HTTP methods (e.g., `POST /.../listKeys`) while remaining logically read-only. For these, displaying `-WhatIf` and `-Confirm` is misleading.
+
+Use `suppress-should-process` to explicitly disable `SupportsShouldProcess` for selected cmdlets so that `-WhatIf` and `-Confirm` are not generated.
+
+This directive was introduced to address scenarios like issue [#704](https://github.com/Azure/autorest.powershell/issues/704), where `listKeys` style operations were generated with unnecessary confirmation switches.
+
+Usage:
+- Target the cmdlet with the usual command filters (`verb`, `subject`, `subject-prefix`, and/or `variant`).
+- Set `suppress-should-process: true` under `set`.
+
+```yaml $false
+# Disable -WhatIf / -Confirm for a logically read-only list keys operation
+directive:
+  - where:
+      verb: Get
+      subject: RedisEnterpriseDatabaseKey
+    set:
+      suppress-should-process: true
+```
+
+Regex example:
+```yaml $false
+# Disable ShouldProcess for all Get-*Keys cmdlets whose subject ends with Keys
+directive:
+  - where:
+      verb: Get
+      subject: (.*)Keys$
+    set:
+      suppress-should-process: true
+```
+
+Notes:
+- Only applies to `command` targets.
+- Has no effect if the cmdlet does not already support ShouldProcess.
+- Use sparingly; only when you are certain the underlying operation is non-mutating.
+
 ### Parameter Rename
 To select a parameter you need to provide the `parameter-name`. Furthermore, if you want to target specific cmdlets you can provide the `subject-prefix`, `subject`, `verb`, and/or `variant` (i.e. parameter-set). For example:
 ```yaml false