Add documentation to all rules supporting a custom suppression target

A subset of PSScriptAnalyzer rules support customising a suppression so
that it only applies to a specific target. This is performed through the
second argument to the `SuppressMessageAttribute` constructor, which is
otherwise an empty string to apply the rule globally within its scope.

This commit adds documentation to all rules which support customising
the target of the suppression, which until now was largely undocumented.

Author: ralish

docs/Rules/AvoidAssignmentToAutomaticVariable.md

@@ -54,6 +54,30 @@ this rule:
 - Add the appropriate rule suppression attributes to your code to suppress the rule for specific
   code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][02].
 
+## Suppression
+
+As with other rules, you can suppress this rule by adding a suppression attribute to the `param`
+block of a function or script. An empty string as the second argument suppresses every violation
+of the rule in that scope.
+
+```powershell
+[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidAssignmentToAutomaticVariable', '')]
+```
+
+To suppress the rule for a single automatic variable, pass the variable name without the leading
+`$` as the second argument. The name isn't case sensitive.
+
+```powershell
+function Test-Script {
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidAssignmentToAutomaticVariable', 'Error')]
+    param(
+        [String]$ErrorMessage
+    )
+
+    $Error = "Error occurred: $ErrorMessage"
+}
+```
+
 <!-- Link references -->
 [01]: /powershell/module/microsoft.powershell.core/about/about_automatic_variables
-[02]: ../using-scriptanalyzer.md
+[02]: ../using-scriptanalyzer.md#suppressing-rules

docs/Rules/AvoidDefaultValueForMandatoryParameter.md

@@ -56,7 +56,30 @@ this rule:
 - Create a custom rule configuration file to include only the rules you want or exclude the rules
   you don't want.
 - Add the appropriate rule suppression attributes to your code to suppress the rule for specific
-  code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][02].
+  code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][01].
+
+## Suppression
+
+As with other rules, you can suppress this rule by adding a suppression attribute to the `param`
+block of a function or script. An empty string as the second argument suppresses every violation
+of the rule in that scope.
+
+```powershell
+[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidDefaultValueForMandatoryParameter', '')]
+```
+
+To suppress the rule for a single parameter, pass the parameter name without the leading `$` as
+the second argument. The name isn't case sensitive.
+
+```powershell
+function Test-Script {
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidDefaultValueForMandatoryParameter', 'Parameter')]
+    param(
+        [Parameter(Mandatory)]
+        $Parameter = 'Default Value'
+    )
+}
+```
 
 <!-- Link references -->
-[02]: ../using-scriptanalyzer.md
+[01]: ../using-scriptanalyzer.md#suppressing-rules

docs/Rules/AvoidDynamicallyCreatingVariableNames.md

@@ -69,6 +69,33 @@ Rules = @{
 
   Enable or disable the rule during ScriptAnalyzer invocation.
 
+## Suppression
+
+As with other rules, you can suppress this rule by adding a suppression attribute to the `param`
+block of a function or script. An empty string as the second argument suppresses every violation
+of the rule in that scope.
+
+```powershell
+[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidDynamicallyCreatingVariableNames', '')]
+```
+
+To suppress the rule for a single `New-Variable` call, pass the value of its `Name` argument
+exactly as it's written in the call, without any enclosing double quotes, as the second argument.
+For example, use `'My$_'` for `New-Variable -Name "My$_"` and `'$name'` for
+`New-Variable -Name $name`. Enclose the second argument in single quotes so that PowerShell
+doesn't try to expand it.
+
+```powershell
+function Test-Script {
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidDynamicallyCreatingVariableNames', 'My$_')]
+    param()
+
+    'One', 'Two', 'Three' | ForEach-Object -Begin { $i = 1 } -Process {
+        New-Variable -Name "My$_" -Value ($i++)
+    }
+}
+```
+
 ## References
 
 - [New-Variable][02]

docs/Rules/AvoidGlobalFunctions.md

@@ -12,7 +12,7 @@ title: AvoidGlobalFunctions
 
 ## Description
 
-This rule detects function definitions that use the `global:` scope modifier on the function name to
+This rule detects function definitions that use the `Global:` scope modifier on the function name to
 define a function in the global scope. Global functions can unintentionally override existing
 functions in the session, leading to unexpected behavior and name collisions. Name collisions make
 it difficult for module consumers to diagnose issues and maintain code reliability.
@@ -25,7 +25,7 @@ scope modifiers. To learn more, see [about_Scopes][01].
 ### Noncompliant
 
 ```powershell
-function global:functionName {}
+function Global:functionName {}
 ```
 
 ### Compliant
@@ -44,6 +44,27 @@ this rule:
 - Add the appropriate rule suppression attributes to your code to suppress the rule for specific
   code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][02].
 
+## Suppression
+
+As with other rules, you can suppress this rule by adding a suppression attribute to the `param`
+block of a function or script. An empty string as the second argument suppresses every violation
+of the rule in that scope.
+
+```powershell
+[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidGlobalFunctions', '')]
+```
+
+To suppress the rule for a single function, pass the function name, including the `Global:` scope
+modifier, as the second argument. The name isn't case sensitive. This is useful when the attribute
+is applied at module scope and covers more than one function.
+
+```powershell
+[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidGlobalFunctions', 'Global:Test-Script')]
+param()
+
+function Global:Test-Script {}
+```
+
 <!-- link references -->
 [01]: /powershell/module/microsoft.powershell.core/about/about_scopes
-[02]: ../using-scriptanalyzer.md
+[02]: ../using-scriptanalyzer.md#suppressing-rules

docs/Rules/AvoidGlobalVars.md

@@ -26,7 +26,7 @@ variables include:
 
 This rule doesn't detect use of the `New-Variable` cmdlet to create variables in the global scope or
 the other `*-Variable` cmdlets to work with variables in the global scope. It only detects variable
-expressions with the global scope modifier, like `$global:example`.
+expressions with the global scope modifier, like `$Global:example`.
 
 This rule doesn't apply to variable expressions that use the global scope modifier where the
 variable name is for an [automatic variable][01] or a [preference variable][02].
@@ -68,8 +68,32 @@ this rule:
 - Add the appropriate rule suppression attributes to your code to suppress the rule for specific
   code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][04].
 
+## Suppression
+
+As with other rules, you can suppress this rule by adding a suppression attribute to the `param`
+block of a function or script. An empty string as the second argument suppresses every violation
+of the rule in that scope.
+
+```powershell
+[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidGlobalVars', '')]
+```
+
+To suppress the rule for a single variable, pass the variable name, including the `Global:` scope
+modifier, as the second argument. The name isn't case sensitive.
+
+```powershell
+function Test-Script {
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidGlobalVars', 'Global:Variable')]
+    param(
+        [String]$Parameter
+    )
+
+    $Global:Variable = $Parameter
+}
+```
+
 <!-- link references -->
 [01]: /powershell/module/microsoft.powershell.core/about/about_automatic_variables
 [02]: /powershell/module/microsoft.powershell.core/about/about_preference_variables
 [03]: /powershell/module/microsoft.powershell.core/about/about_scopes
-[04]: ../using-scriptanalyzer.md
+[04]: ../using-scriptanalyzer.md#suppressing-rules

docs/Rules/AvoidNullOrEmptyHelpMessageAttribute.md

@@ -83,6 +83,29 @@ this rule:
 - Add the appropriate rule suppression attributes to your code to suppress the rule for specific
   code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][02].
 
+## Suppression
+
+As with other rules, you can suppress this rule by adding a suppression attribute to the `param`
+block of a function or script. An empty string as the second argument suppresses every violation
+of the rule in that scope.
+
+```powershell
+[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidNullOrEmptyHelpMessageAttribute', '')]
+```
+
+To suppress the rule for a single parameter, pass the parameter name without the leading `$` as
+the second argument. The name isn't case sensitive.
+
+```powershell
+function Test-Script {
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidNullOrEmptyHelpMessageAttribute', 'Parameter')]
+    param(
+        [Parameter(HelpMessage = '')]
+        [String]$Parameter
+    )
+}
+```
+
 <!-- link references -->
 [01]: /powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters#helpmessage-argument
-[02]: ../using-scriptanalyzer.md
+[02]: ../using-scriptanalyzer.md#suppressing-rules

docs/Rules/AvoidUsingAllowUnencryptedAuthentication.md

@@ -45,7 +45,30 @@ this rule:
 - Add the appropriate rule suppression attributes to your code to suppress the rule for specific
   code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][03].
 
+## Suppression
+
+As with other rules, you can suppress this rule by adding a suppression attribute to the `param`
+block of a function or script. An empty string as the second argument suppresses every violation
+of the rule in that scope.
+
+```powershell
+[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingAllowUnencryptedAuthentication', '')]
+```
+
+To suppress the rule for a single command, pass the command name as it appears in the call as the
+second argument. The name isn't case sensitive, but it must match what's written in the script, so
+a call made through an alias needs the alias name.
+
+```powershell
+function Test-Script {
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingAllowUnencryptedAuthentication', 'Invoke-WebRequest')]
+    param()
+
+    Invoke-WebRequest foo -AllowUnencryptedAuthentication
+}
+```
+
 <!-- Link references -->
 [01]: /powershell/module/microsoft.powershell.utility/invoke-webrequest
 [02]: /powershell/module/microsoft.powershell.utility/invoke-restmethod
-[03]: ../using-scriptanalyzer.md
+[03]: ../using-scriptanalyzer.md#suppressing-rules

docs/Rules/AvoidUsingBrokenHashAlgorithms.md

@@ -41,7 +41,30 @@ this rule:
 - Create a custom rule configuration file to include only the rules you want or exclude the rules
   you don't want.
 - Add the appropriate rule suppression attributes to your code to suppress the rule for specific
-  code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][02].
+  code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][01].
+
+## Suppression
+
+As with other rules, you can suppress this rule by adding a suppression attribute to the `param`
+block of a function or script. An empty string as the second argument suppresses every violation
+of the rule in that scope.
+
+```powershell
+[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingBrokenHashAlgorithms', '')]
+```
+
+To suppress the rule for a single command, pass the command name as it appears in the call as the
+second argument. The name isn't case sensitive, but it must match what's written in the script, so
+a call made through an alias needs the alias name.
+
+```powershell
+function Test-Script {
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingBrokenHashAlgorithms', 'Get-FileHash')]
+    param()
+
+    Get-FileHash foo.txt -Algorithm MD5
+}
+```
 
 <!-- Link references -->
-[02]: ../using-scriptanalyzer.md
+[01]: ../using-scriptanalyzer.md#suppressing-rules

docs/Rules/AvoidUsingCmdletAliases.md

@@ -65,7 +65,31 @@ using this rule:
 - Create a custom rule configuration file to include only the rules you want or exclude the rules
   you don't want.
 - Add the appropriate rule suppression attributes to your code to suppress the rule for specific
-  code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][02].
+  code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][01].
+
+## Suppression
+
+As with other rules, you can suppress this rule by adding a suppression attribute to the `param`
+block of a function or script. An empty string as the second argument suppresses every violation
+of the rule in that scope.
+
+```powershell
+[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingCmdletAliases', '')]
+```
+
+To suppress the rule for a single alias, pass the alias as the second argument. For an implicit
+alias, pass the command name as it's written without the `Get-` prefix, for example `'verb'` for
+`verb`. The name isn't case sensitive. To allow an alias everywhere, use the `allowlist` setting
+instead.
+
+```powershell
+function Test-Script {
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingCmdletAliases', 'gps')]
+    param()
+
+    gps | Where-Object { $_.WorkingSet -gt 20000000 }
+}
+```
 
 <!-- Link references -->
-[02]: ../using-scriptanalyzer.md
+[01]: ../using-scriptanalyzer.md#suppressing-rules

docs/Rules/AvoidUsingComputerNameHardcoded.md

@@ -48,7 +48,30 @@ this rule:
 - Create a custom rule configuration file to include only the rules you want or exclude the rules
   you don't want.
 - Add the appropriate rule suppression attributes to your code to suppress the rule for specific
-  code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][02].
+  code blocks. For more information, see the _Suppressing rules_ section of [Using PSScriptAnalyzer][01].
+
+## Suppression
+
+As with other rules, you can suppress this rule by adding a suppression attribute to the `param`
+block of a function or script. An empty string as the second argument suppresses every violation
+of the rule in that scope.
+
+```powershell
+[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingComputerNameHardcoded', '')]
+```
+
+To suppress the rule for a single command, pass the command name as it appears in the call as the
+second argument. The name isn't case sensitive, but it must match what's written in the script, so
+a call made through an alias needs the alias name.
+
+```powershell
+function Test-Script {
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingComputerNameHardcoded', 'Invoke-Command')]
+    param()
+
+    Invoke-Command -ComputerName HardcodedHostname -Port 343
+}
+```
 
 <!-- Link references -->
-[02]: ../using-scriptanalyzer.md
+[01]: ../using-scriptanalyzer.md#suppressing-rules