Sync docs updates to source repo

Author: sdwheeler

docs/Rules/AlignAssignmentStatement.md

@@ -1,6 +1,6 @@
 ---
 description: Align assignment statement
-ms.date: 03/20/2026
+ms.date: 06/12/2026
 ms.topic: reference
 title: AlignAssignmentStatement
 ---
@@ -10,13 +10,20 @@ title: AlignAssignmentStatement
 
 ## Description
 
-Consecutive assignment statements are more readable when they're aligned. Assignments are considered
-aligned when their `equals` signs line up vertically.
+This rule detects misaligned assignment operators in hashtables and enum definitions. Consecutive
+assignment statements are easier to read and maintain when their assignment operators align
+vertically.
 
-This rule looks at the key-value pairs in hashtables (including DSC configurations) as well as enum
+This rule checks key-value pairs in hashtables and enum member definitions to ensure that the `=`
+signs line up. Use this rule to enforce consistent formatting in multiline hashtables and enum
 definitions.
 
-Consider the following example with a hashtable and enum that isn't aligned.
+The rule ignores assignments within hashtables and enums that appear on the same line as other
+assignments. For example, the rule ignores `$h = @{ a = 1; b = 2 }`.
+
+## Example
+
+### Noncompliant
 
 ```powershell
 $hashtable = @{
@@ -30,7 +37,7 @@ enum Enum {
 }
 ```
 
-Alignment in this case would look like the following.
+### Compliant
 
 ```powershell
 $hashtable = @{
@@ -44,9 +51,6 @@ enum Enum {
 }
 ```
 
-The rule ignores any assignments within hashtables and enums which are on the same line as others.
-For example, the rule ignores `$h = @{a = 1; b = 2}`.
-
 ## Configuration
 
 ```powershell
@@ -62,22 +66,24 @@ Rules = @{
 }
 ```
 
-### Parameters
+## Parameters
 
-#### Enable: bool (Default value is `$false`)
+### Enable
 
-Enable or disable the rule during ScriptAnalyzer invocation.
+This parameter controls whether ScriptAnalyzer checks the code against this rule. It accepts a
+boolean value. To enable this rule, set this parameter to `$true`. The default value is `$false`.
 
-#### CheckHashtable: bool (Default value is `$true`)
+### CheckHashtable
 
-Enforce alignment of assignment statements in a hashtable and in a DSC Configuration. There is only
-one setting for hashtable and DSC configuration because the property value pairs in a DSC
-configuration are parsed as key-value pairs of a hashtable.
+This parameter controls whether ScriptAnalyzer checks assignment alignment in hashtables and Desired
+State Configuration (DSC) configurations. It accepts a boolean value. To disable this check, set
+this parameter to `$false`. The default value is `$true`.
 
-#### AlignHashtableKvpWithInterveningComment: bool (Default value is `$true`)
+### AlignHashtableKvpWithInterveningComment
 
-Include key-value pairs in the alignment that have an intervening comment - that is to say a comment
-between the key name and the equals sign.
+This parameter controls whether ScriptAnalyzer includes hashtable key-value pairs that contain an
+intervening comment when determining alignment. It accepts a boolean value. To exclude these lines,
+set this parameter to `$false`. The default value is `$true`.
 
 Consider the following:
 
@@ -89,7 +95,8 @@ $hashtable = @{
 }
 ```
 
-With this setting disabled, the line with the comment is ignored, and it would be aligned like so:
+With this setting disabled, the line with the comment is ignored. The equal signs are aligned for
+the remaining lines:
 
 ```powershell
 $hashtable = @{
@@ -99,7 +106,7 @@ $hashtable = @{
 }
 ```
 
-With it enabled, the comment line is included in alignment:
+With this setting enabled, the equal signs are aligned for all lines:
 
 ```powershell
 $hashtable = @{
@@ -109,49 +116,23 @@ $hashtable = @{
 }
 ```
 
-#### CheckEnum: bool (Default value is `$true`)
-
-Enforce alignment of assignment statements of an Enum definition.
-
-#### AlignEnumMemberWithInterveningComment: bool (Default value is `$true`)
-
-Include enum members in the alignment that have an intervening comment - that is to say a comment
-between the member name and the equals sign.
-
-Consider the following:
-
-```powershell
-enum Enum {
-    member = 1
-    anotherMember <#A Comment#> = 2
-    anotherDifferentMember = 3
-}
-```
-
-With this setting disabled, the line with the comment is ignored, and it would be aligned like so:
+### CheckEnum
 
-```powershell
-enum Enum {
-    member                 = 1
-    anotherMember <#A Comment#> = 2
-    anotherDifferentMember = 3
-}
-```
+This parameter controls whether ScriptAnalyzer checks assignment alignment in enum member
+definitions. It accepts a boolean value. To disable this check, set this parameter to `$false`. The
+default value is `$true`.
 
-With it enabled, the comment line is included in alignment:
+### AlignEnumMemberWithInterveningComment
 
-```powershell
-enum Enum {
-    member                      = 1
-    anotherMember <#A Comment#> = 2
-    anotherDifferentMember      = 3
-}
-```
+This parameter controls whether ScriptAnalyzer includes enum members that contain an intervening
+comment when determining alignment. It accepts a boolean value. To exclude these lines, set this
+parameter to `$false`. The default value is `$true`.
 
-#### IncludeValuelessEnumMembers: bool (Default value is `$true`)
+### IncludeValuelessEnumMembers
 
-Include enum members in the alignment that don't have an explicitly assigned value. Enums don't
-need to be given a value when they're defined.
+This parameter controls whether ScriptAnalyzer includes enum members without explicitly assigned
+values when determining alignment. It accepts a boolean value. To exclude valueless members, set
+this parameter to `$false`. The default value is `$true`.
 
 Consider the following:
 
@@ -164,7 +145,7 @@ enum Enum {
 ```
 
 With this setting disabled, the third line, which has no value, isn't considered when choosing where
-to align assignments. It would be aligned like so:
+to align assignments.
 
 ```powershell
 enum Enum {

docs/Rules/AvoidAssignmentToAutomaticVariable.md

@@ -1,6 +1,6 @@
 ---
 description: Changing automatic variables might have undesired side effects
-ms.date: 06/28/2023
+ms.date: 06/12/2026
 ms.topic: reference
 title: AvoidAssignmentToAutomaticVariable
 ---
@@ -10,11 +10,15 @@ title: AvoidAssignmentToAutomaticVariable
 
 ## Description
 
-PowerShell has built-in variables known as automatic variables. Many of them are read-only and
-PowerShell throws an error when trying to assign an value on those. Other automatic variables should
-only be assigned in certain special cases to achieve a certain effect as a special technique.
+This rule detects assignments to automatic variables and parameter names that use automatic variable
+names. PowerShell automatically defines variables that store internal state information and manages
+them on its own. Even though you _can_ override many automatic variables, doing so can have
+unexpected effects for users and make your code harder to maintain and debug.
 
-To understand more about automatic variables, see `Get-Help about_Automatic_Variables`.
+Avoid using automatic variable names in your functions and parameters. Reserve automatic variables
+for PowerShell's internal use only, and rely on them only to read state information.
+
+To learn more, see [about_Automatic_Variables][01].
 
 <!-- TODO
 Ability to suppress was added in https://github.com/PowerShell/PSScriptAnalyzer/pull/1896
@@ -27,9 +31,9 @@ Use variable names in functions or their parameters that do not conflict with au
 
 ## Example
 
-### Wrong
+### Noncompliant
 
-The variable `$Error` is an automatic variables that exists in the global scope and should therefore
+The variable `$Error` is an automatic variable that exists in the global scope and should therefore
 never be used as a variable or parameter name.
 
 ```powershell
@@ -40,8 +44,12 @@ function foo($Error){ }
 function Get-CustomErrorMessage($ErrorMessage){ $Error = "Error occurred: $ErrorMessage" }
 ```
 
-### Correct
+### Compliant
 
 ```powershell
 function Get-CustomErrorMessage($ErrorMessage){ $FinalErrorMessage = "Error occurred: $ErrorMessage" }
 ```
+
+<!-- Link reference definitions -->
+
+[01]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_automatic_variables

docs/Rules/AvoidDefaultValueForMandatoryParameter.md

@@ -1,6 +1,6 @@
 ---
 description: Avoid Default Value For Mandatory Parameter
-ms.date: 06/28/2023
+ms.date: 06/12/2026
 ms.topic: reference
 title: AvoidDefaultValueForMandatoryParameter
 ---
@@ -10,13 +10,14 @@ title: AvoidDefaultValueForMandatoryParameter
 
 ## Description
 
-Mandatory parameters should not have a default values because there is no scenario where the default
-can be used. PowerShell prompts for a value if the parameter value is not specified when calling the
-function.
+This rule detects when mandatory parameters have default values assigned. Mandatory parameters
+shouldn't have default values because they can't be used. When a parameter is marked as mandatory,
+PowerShell always prompts the user for a value if one isn't supplied when calling the function. Any
+default value assigned to a mandatory parameter is unreachable and serves no purpose.
 
 ## Example
 
-### Wrong
+### Noncompliant
 
 ```powershell
 function Test
@@ -31,7 +32,7 @@ function Test
 }
 ```
 
-### Correct
+### Compliant
 
 ```powershell
 function Test

docs/Rules/AvoidDefaultValueSwitchParameter.md

@@ -1,6 +1,6 @@
 ---
-description: Switch Parameters Should Not Default To True
-ms.date: 12/05/2024
+description: Switch parameters should not default to $true
+ms.date: 06/12/2026
 ms.topic: reference
 title: AvoidDefaultValueSwitchParameter
 ---
@@ -10,23 +10,24 @@ title: AvoidDefaultValueSwitchParameter
 
 ## Description
 
-If your parameter takes only `true` and `false`, define the parameter as type `[Switch]`. PowerShell
-treats a switch parameter as `true` when it's used with a command. If the parameter isn't included
-with the command, PowerShell considers the parameter to be false. Don't define `[Boolean]`
-parameters.
+This rule detects switch parameters that are assigned a default value of `$true`. Switch parameters
+shouldn't have default values. By design, a switch parameter is `$false` when not specified and
+`$true` when included in the command. Assigning a default value of `$true` to a switch parameter
+violates this design principle and can cause unexpected behavior.
 
-You shouldn't define a switch parameter with a default value of `$true` because this isn't the
-expected behavior of a switch parameter.
+If your parameter needs to accept only `true` and `false` values, use the `[Switch]` type instead of
+`[Boolean]`. PowerShell automatically handles switch parameters correctly without requiring a
+default value.
 
-## How
+To fix this issue, remove the default value from the switch parameter declaration. The switch
+naturally defaults to `$false` when not specified, allowing your logic to respond appropriately to
+the caller's input.
 
-Change the default value of the switch parameter to be `$false` or don't provide a default value.
-Write the logic of the script to assume that the switch parameter default value is `$false` or not
-provided.
+To learn more, see [Strongly Encouraged Development Guidelines][01].
 
 ## Example
 
-### Wrong
+### Noncompliant
 
 ```powershell
 function Test-Script
@@ -44,7 +45,7 @@ function Test-Script
 }
 ```
 
-### Correct
+### Compliant
 
 ```powershell
 function Test-Script
@@ -69,9 +70,5 @@ function Test-Script
 }
 ```
 
-## More information
-
-- [Strongly Encouraged Development Guidelines][01]
-
 <!-- link references -->
 [01]: https://learn.microsoft.com/powershell/scripting/developer/cmdlet/strongly-encouraged-development-guidelines#parameters-that-take-true-and-false

docs/Rules/AvoidExclaimOperator.md

@@ -1,6 +1,6 @@
 ---
 description: Avoid exclaim operator
-ms.date: 03/26/2024
+ms.date: 05/28/2026
 ms.topic: reference
 title: AvoidExclaimOperator
 ---
@@ -10,39 +10,32 @@ title: AvoidExclaimOperator
 
 ## Description
 
-Avoid using the negation operator (`!`). Use `-not` for improved readability.
+This rule detects the use of the negation operator (an exclamation mark, `!`) and recommends using
+the `-not` operator instead for improved readability and consistency with PowerShell conventions.
 
-> [!NOTE]
-> This rule is not enabled by default. The user needs to enable it through settings.
+The `-not` operator is more explicit and aligns with PowerShell's verbose style, making code
+easier to understand at a glance.
 
-## How to Fix
+This rule is **disabled** by default. Enable it explicitly during ScriptAnalyzer invocation if
+desired.
 
 ## Example
 
-### Wrong
+### Noncompliant
 
 ```powershell
 $MyVar = !$true
 ```
 
-### Correct
+### Compliant
 
 ```powershell
 $MyVar = -not $true
 ```
 
-## Configuration
+## Parameters
 
-```powershell
-Rules = @{
-    PSAvoidExclaimOperator  = @{
-        Enable = $true
-    }
-}
-```
-
-### Parameters
-
-- `Enable`: **bool** (Default value is `$false`)
+### Enable
 
-  Enable or disable the rule during ScriptAnalyzer invocation.
+This parameter controls whether ScriptAnalyzer checks the code against this rule. It accepts a
+boolean value. To enable this rule, set this parameter to `$true`. The default value is `$false`.