Sync docs changes from docs repo

Author: sdwheeler

docs/Cmdlets/Invoke-Formatter.md

@@ -9,6 +9,7 @@ schema: 2.0.0
 # Invoke-Formatter
 
 ## SYNOPSIS
+
 Formats a script text based on the input settings or default settings.
 
 ## SYNTAX

docs/Cmdlets/Invoke-ScriptAnalyzer.md

@@ -1,7 +1,7 @@
 ---
 external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml
 Module Name: PSScriptAnalyzer
-ms.date: 10/07/2021
+ms.date: 07/23/2026
 online version: https://learn.microsoft.com/powershell/module/psscriptanalyzer/invoke-scriptanalyzer?view=ps-modules&wt.mc_id=ps-gethelp
 schema: 2.0.0
 ---
@@ -107,7 +107,12 @@ This example runs all rules except for **PSAvoidUsingCmdletAliases** and
 subdirectories.
 
 ```powershell
-Invoke-ScriptAnalyzer -Path C:\ps-test\MyModule -Recurse -ExcludeRule PSAvoidUsingCmdletAliases, PSAvoidUsingInternalURLs
+$invokeScriptAnalyzerSplat = @{
+    Path = 'C:\ps-test\MyModule'
+    Recurse = $true
+    ExcludeRule = 'PSAvoidUsingCmdletAliases', 'PSAvoidUsingInternalURLs'
+}
+Invoke-ScriptAnalyzer @invokeScriptAnalyzerSplat
 ```
 
 ### EXAMPLE 5 - Run Script Analyzer with custom rules
@@ -116,13 +121,19 @@ This example runs Script Analyzer on `Test-Script.ps1` with the standard rules a
 `C:\CommunityAnalyzerRules` path.
 
 ```powershell
-Invoke-ScriptAnalyzer -Path D:\test_scripts\Test-Script.ps1 -CustomRulePath C:\CommunityAnalyzerRules -IncludeDefaultRules
+$invokeScriptAnalyzerSplat = @{
+    Path = 'D:\test_scripts\Test-Script.ps1'
+    CustomRulePath = 'C:\CommunityAnalyzerRules'
+    IncludeDefaultRules = $true
+}
+Invoke-ScriptAnalyzer @invokeScriptAnalyzerSplat
 ```
 
 ### EXAMPLE 6 - Run only the rules that are Error severity and have the PSDSC source name
 
 ```powershell
-$DSCError = Get-ScriptAnalyzerRule -Severity Error | Where SourceName -eq PSDSC
+$DSCError = Get-ScriptAnalyzerRule -Severity Error |
+    Where-Object SourceName -eq PSDSC
 $Path = "$home\Documents\WindowsPowerShell\Modules\MyDSCModule"
 Invoke-ScriptAnalyzerRule -Path $Path -IncludeRule $DSCError -Recurse
 ```
@@ -145,34 +156,32 @@ function Get-Widgets
 {
     [CmdletBinding()]
     [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseSingularNouns", "")]
-    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingCmdletAliases", "", Justification="Resolution in progress.")]
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingCmdletAliases", "",
+        Justification="Resolution in progress.")]
     Param()
 
-    dir $pshome
+    dir $PSHOME
     ...
 }
 
 Invoke-ScriptAnalyzer -Path .\Get-Widgets.ps1
 ```
 
 ```Output
-RuleName                            Severity     FileName   Line  Message
---------                            --------     --------   ----  -------
-PSProvideCommentHelp                Information  ManageProf 14    The cmdlet 'Get-Widget' does not have a help comment.
-                                                 iles.psm1
+RuleName                  Severity     FileName            Line  Message
+--------                  --------     --------            ----  -------
+PSProvideCommentHelp      Information  ManageProfiles.psm1 14    The cmdlet 'Get-Widget' does not have a help comment.
 ```
 
 ```powershell
 Invoke-ScriptAnalyzer -Path .\Get-Widgets.ps1 -SuppressedOnly
 ```
 
 ```Output
-Rule Name                           Severity     File Name  Line  Justification
----------                           --------     ---------  ----  -------------
-PSAvoidUsingCmdletAliases           Warning      ManageProf 21    Resolution in progress.
-                                                 iles.psm1
-PSUseSingularNouns                  Warning      ManageProf 14
-                                                 iles.psm1
+Rule Name                   Severity  File Name           Line  Justification
+---------                   --------  ---------           ----  -------------
+PSAvoidUsingCmdletAliases   Warning   ManageProfiles.psm1 21    Resolution in progress.
+PSUseSingularNouns          Warning   ManageProfiles.psm1 14
 ```
 
 The second command uses the **SuppressedOnly** parameter to report violations of the rules that are
@@ -192,7 +201,7 @@ value of the **Profile** parameter is the path to the Script Analyzer profile.
     ExcludeRules = '*WriteHost'
 }
 
-Invoke-ScriptAnalyzer -Path $pshome\Modules\BitLocker -Settings .\ScriptAnalyzerProfile.txt
+Invoke-ScriptAnalyzer -Path $PSHOME\Modules\BitLocker -Settings .\ScriptAnalyzerProfile.txt
 ```
 
 If you include a conflicting parameter in the `Invoke-ScriptAnalyzer` command, such as
@@ -208,15 +217,16 @@ Invoke-ScriptAnalyzer -ScriptDefinition "function Get-Widgets {Write-Host 'Hello
 ```
 
 ```Output
-RuleName                            Severity     FileName   Line  Message
---------                            --------     --------   ----  -------
-PSAvoidUsingWriteHost               Warning                 1     Script
-                                                                  because
-                                                                  there i
-                                                                  suppres
-                                                                  Write-O
-PSUseSingularNouns                  Warning                 1     The cmd
-                                                                  noun sh
+RuleName               Severity     FileName   Line  Message
+--------               --------     --------   ----  -------
+PSAvoidUsingWriteHost  Warning                 1     Script definition uses Write-Host. Avoid using
+                                                     Write-Host because it might not work in all hosts,
+                                                     does not work when there is no host, and (prior
+                                                     to PS 5.0) cannot be suppressed, captured, or
+                                                     redirected. Instead, use Write-Output, Write-Verbose,
+                                                     or Write-Information.
+PSUseSingularNouns     Warning                 1     The cmdlet 'Get-Widgets' uses a plural noun. A
+                                                     singular noun should be used instead.
 ```
 
 When you use the **ScriptDefinition** parameter, the **FileName** property of the
@@ -513,7 +523,7 @@ following keys:
 
 The keys and values in the profile are interpreted as if they were standard parameters and values of
 `Invoke-ScriptAnalyzer`, similar to splatting. For more information, see
-[about_Splatting](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_splatting).
+[about_Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting).
 
 ```yaml
 Type: Object
@@ -536,15 +546,14 @@ Valid values are:
 
 - Error
 - Warning
-- Information.
-
-You can specify one ore more severity values.
+- Information
+- ParseError
 
-The parameter filters the rules violations only after running all rules. To filter rules
-efficiently, use `Get-ScriptAnalyzerRule` to select the rules you want to run.
+You can specify one or more severity values.
 
-The **Severity** parameter takes precedence over **IncludeRule**. For example, if **Severity** is
-`Error`, you cannot use **IncludeRule** to include a `Warning` rule.
+The parameter filters the rule violation output only after running all rules. It doesn't filter
+which rules are run. To filter rules efficiently, use `Get-ScriptAnalyzerRule` to select the rules
+you want to run.
 
 ```yaml
 Type: String[]

docs/Cmdlets/New-ScriptAnalyzerSettingsFile.md

@@ -1,35 +1,34 @@
 ---
 external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml
 Module Name: PSScriptAnalyzer
-ms.date: 04/17/2026
+ms.date: 07/21/2026
 schema: 2.0.0
 ---
-
 # New-ScriptAnalyzerSettingsFile
 
 ## SYNOPSIS
+
 Creates a new PSScriptAnalyzer settings file.
 
 ## SYNTAX
 
 ```
-New-ScriptAnalyzerSettingsFile [[-Path] <string>] [-BaseOnPreset <string>] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]
+New-ScriptAnalyzerSettingsFile [[-Path] <string>] [-BaseOnPreset <string>] [-Force]
+ [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
 
 The `New-ScriptAnalyzerSettingsFile` cmdlet creates a `PSScriptAnalyzerSettings.psd1` file in the
-specified directory.
-
-When the **BaseOnPreset** parameter is provided, the generated file contains the rules and
-configuration defined by the given preset.
+specified directory. By default, the generated file includes all current rules in the `IncludeRules`
+list and populates the `Rules` section with all configurable properties, set to their default
+values.
 
-When **BaseOnPreset** is not provided, the generated file includes all current rules in the
-`IncludeRules` list and populates the `Rules` section with all configurable properties, set to their
-default values.
+When you provide the **BaseOnPreset**, the generated file contains the rules and configuration
+defined by the given preset file.
 
-If a settings file already exists at the target path, the cmdlet emits a terminating error unless
-the **Force** parameter is specified - in which case it's overwritten.
+If a settings file already exists at the target path the command fails unless you use the **Force**
+parameter to overwrite the existing file.
 
 ## EXAMPLES
 
@@ -71,7 +70,8 @@ Shows what the cmdlet would do without actually writing the file.
 
 ### -Path
 
-The directory where the settings file will be created. Defaults to the current working directory when not specified.
+The directory where the settings file is created. Defaults to the current working directory when not
+specified.
 
 ```yaml
 Type: String
@@ -104,7 +104,7 @@ Accept wildcard characters: False
 
 ### -WhatIf
 
-Shows what would happen if the cmdlet runs. The cmdlet is not run.
+Shows what would happen if the cmdlet runs. The cmdlet isn't run.
 
 ```yaml
 Type: SwitchParameter
@@ -172,7 +172,6 @@ The cmdlet returns a **FileInfo** object representing the created settings file.
 The output file is always named `PSScriptAnalyzerSettings.psd1` so that the automatic settings
 discovery in `Invoke-ScriptAnalyzer` picks it up when analysing scripts in the same directory.
 
-Note: Relative paths in `CustomRulePath` are resolved from the caller's current working directory,
 Relative paths in `CustomRulePath` are resolved from the caller's current working directory,
 not from the location of the settings file. This matches `Invoke-ScriptAnalyzer` behavior.
 

docs/Cmdlets/PSScriptAnalyzer.md

@@ -1,6 +1,6 @@
 ---
 Download Help Link: https://aka.ms/ps-modules-help
-Help Version: 1.25.0
+Help Version: 1.26.0
 Locale: en-US
 Module Guid: d6245802-193d-4068-a631-8863a4342a18
 Module Name: PSScriptAnalyzer
@@ -31,3 +31,12 @@ Formats a script text based on the input settings or default settings.
 ### [Invoke-ScriptAnalyzer](Invoke-ScriptAnalyzer.md)
 
 Evaluates a script or module based on selected best practice rules
+
+### [New-ScriptAnalyzerSettingsFile](New-ScriptAnalyzerSettingsFile.md)
+
+Creates a new PSScriptAnalyzer settings file.
+
+### [Test-ScriptAnalyzerSettingsFile](Test-ScriptAnalyzerSettingsFile.md)
+
+Validates a PSScriptAnalyzer settings file as a self-contained unit.
+

docs/Cmdlets/Test-ScriptAnalyzerSettingsFile.md

@@ -1,13 +1,13 @@
 ---
 external help file: Microsoft.Windows.PowerShell.ScriptAnalyzer.dll-Help.xml
 Module Name: PSScriptAnalyzer
-ms.date: 04/17/2026
+ms.date: 07/21/2026
 schema: 2.0.0
 ---
-
 # Test-ScriptAnalyzerSettingsFile
 
 ## SYNOPSIS
+
 Validates a PSScriptAnalyzer settings file as a self-contained unit.
 
 ## SYNTAX
@@ -25,19 +25,19 @@ see when given the same file.
 
 The cmdlet verifies that:
 
-- The file can be parsed as a PowerShell data file.
+- The file is parseable as a PowerShell data file
 - All rule names referenced in `IncludeRules`, `ExcludeRules`, and `Rules` correspond to known
-  rules (wildcard patterns are skipped).
-- All `Severity` values are valid.
-- Rule option names in the `Rules` section correspond to actual configurable properties.
-- Rule option values that are constrained to a set of choices contain a valid value.
+  rules (wildcard patterns are skipped)
+- All `Severity` values are valid
+- Rule option names in the `Rules` section correspond to actual configurable properties
+- Rule option values that are constrained to a set of choices contain a valid value
 
-By default, when problems are found the cmdlet outputs a `DiagnosticRecord` for each one, with the
-source extent pointing to the offending text in the file. This is the same object type returned by
-`Invoke-ScriptAnalyzer`, so existing formatting and tooling works out of the box. When the file is
-valid, no output is produced.
+By default, the cmdlet outputs a `DiagnosticRecord` for each problem found. The source extent in the
+diagnostic record points to the offending text in the file. This is the same object type returned by
+`Invoke-ScriptAnalyzer`, so existing formatting and tooling works by default. When the file is
+valid, the command produces no output.
 
-When `-Quiet` is specified the cmdlet returns only `$true` or `$false` and suppresses all
+If you use the **Quiet** parameter, the command only `$true` or `$false` and suppresses all
 diagnostic output.
 
 ## EXAMPLES
@@ -121,26 +121,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ### Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord
 
-Without `-Quiet`, a `DiagnosticRecord` is output for each problem found. Each record includes the
-error message, the source extent (file, line and column), a severity, and the rule name
+Without the **Quiet** parameter, a `DiagnosticRecord` is output for each problem found. Each record
+includes the error message, the source extent (file, line and column), a severity, and the rule name
 `Test-ScriptAnalyzerSettingsFile`. No output is produced when the file is valid.
 
 ### System.Boolean
 
-With `-Quiet`, returns `$true` when the file is valid and `$false` otherwise.
+With the **Quiet** parameter, returns `$true` when the file is valid and `$false` otherwise.
 
 ## NOTES
 
-The cmdlet reads `CustomRulePath`, `RecurseCustomRulePath`, and `IncludeDefaultRules` from the
-settings file so it validates rule names against the same set of rules that `Invoke-ScriptAnalyzer`
-would load. This means the settings file is validated as a self-contained unit without requiring
-extra command-line parameters.
-
-Note: Relative paths in `CustomRulePath` are resolved from the caller's current working directory,
-not from the location of the settings file. This matches `Invoke-ScriptAnalyzer` behaviour.
-
-The `DiagnosticRecord` objects use the same type as `Invoke-ScriptAnalyzer`, so they benefit from
-the same default formatting and can be piped to the same downstream tooling.
+Relative paths in `CustomRulePath` are resolved from the caller's current working directory, not
+from the location of the settings file. This matches `Invoke-ScriptAnalyzer` behaviour.
 
 ## RELATED LINKS