[Freshness] PSScriptAnalyzer Article Updates - Batch 2

reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidLongLines.md

@@ -1,6 +1,6 @@
 ---
 description: Avoid long lines
-ms.date: 03/20/2026
+ms.date: 06/01/2026
 ms.topic: reference
 title: AvoidLongLines
 ---
@@ -10,13 +10,25 @@ title: AvoidLongLines
 
 ## Description
 
-The length of lines, including leading spaces (indentation), should be less than the configured
-number of characters. The default length is 120 characters.
+This rule flags lines that exceed the configured maximum length, including leading spaces
+(indentation). The default maximum line length is 120 characters. This rule is **disabled** by
+default and must be explicitly enabled through rule configuration settings.
 
-> [!NOTE]
-> This rule isn't enabled by default. The user needs to enable it through settings.
+## Example 1
 
-## Configuration
+```
+In this example of sample text, the maximum line length is using the default setting of not exceeding more than 120
+characters.
+```
+
+## Example 2
+
+```
+In this example of sample text, the maximum line length is set to not exceed
+more than 80 characters.
+```
+
+## Configure rule
 
 ```powershell
 Rules = @{
@@ -29,10 +41,15 @@ Rules = @{
 
 ## Parameters
 
-### `Enable`: bool (Default value is `$false`)
+### Enable
+
+Enables (`$true`) the rule during ScriptAnalyzer invocation.
+
+### Disable
 
-Enable or disable the rule during ScriptAnalyzer invocation.
+Disables (`$false`) the rule during ScriptAnalyzer invocation. Default value is `$false`.
 
-### `MaximumLineLength`: int (Default value is 120)
+### MaximumLineLength
 
-Optional parameter to override the default maximum line length.
+This parameter is optional and is used to override the default maximum line length. This parameter
+accepts an integer value. Default value is `120`.

reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidMultipleTypeAttributes.md

@@ -1,6 +1,6 @@
 ---
 description: Avoid multiple type specifiers on parameters.
-ms.date: 06/28/2023
+ms.date: 06/01/2026
 ms.topic: reference
 title: AvoidMultipleTypeAttributes
 ---
@@ -10,16 +10,15 @@ title: AvoidMultipleTypeAttributes
 
 ## Description
 
-Parameters should not have more than one type specifier. Multiple type specifiers on parameters
-can cause runtime errors.
+Parameters shouldn't have multiple type specifiers. When you apply more than one type attribute to a
+parameter, it can lead to unexpected type coercion or runtime errors.
 
-## How
-
-Ensure each parameter has only 1 type specifier.
+Each parameter should have exactly one type specifier to ensure predictable behavior and type
+safety.
 
 ## Example
 
-### Wrong
+### Noncompliant
 
 ```powershell
 function Test-Script
@@ -34,7 +33,7 @@ function Test-Script
 }
 ```
 
-### Correct
+### Compliant
 
 ```powershell
 function Test-Script

reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidNullOrEmptyHelpMessageAttribute.md

@@ -1,6 +1,6 @@
 ---
 description: Avoid using null or empty HelpMessage parameter attribute.
-ms.date: 06/28/2023
+ms.date: 06/01/2026
 ms.topic: reference
 title: AvoidNullOrEmptyHelpMessageAttribute
 ---
@@ -10,16 +10,16 @@ title: AvoidNullOrEmptyHelpMessageAttribute
 
 ## Description
 
-The value of the `HelpMessage` attribute should not be an empty string or a null value as this
-causes PowerShell's interpreter to throw an error when executing the function or cmdlet.
+The `HelpMessage` attribute must contain a meaningful, non-empty string value. Omitting the value
+altogether causes a parse-time syntax error. Using an empty string or null value causes PowerShell
+to raise an error at runtime.
 
-## How
-
-Specify a value for the `HelpMessage` attribute.
+Always provide a descriptive help message that explains the parameter's purpose and expected input
+to users.
 
 ## Example
 
-### Wrong
+### Noncompliant
 
 ```powershell
 Function BadFuncEmptyHelpMessageEmpty
@@ -56,7 +56,7 @@ Function BadFuncEmptyHelpMessageNoAssignment
 }
 ```
 
-### Correct
+### Compliant
 
 ```powershell
 Function GoodFuncHelpMessage

reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidOverwritingBuiltInCmdlets.md

@@ -1,6 +1,6 @@
 ---
 description: Avoid overwriting built in cmdlets
-ms.date: 12/12/2024
+ms.date: 06/01/2026
 ms.topic: reference
 title: AvoidOverwritingBuiltInCmdlets
 ---
@@ -10,16 +10,44 @@ title: AvoidOverwritingBuiltInCmdlets
 
 ## Description
 
-This rule flags cmdlets that are available in a given edition/version of PowerShell on a given
-operating system which are overwritten by a function declaration. It works by comparing function
-declarations against a set of allowlists that ship with PSScriptAnalyzer. These allowlist files are
-used by other PSScriptAnalyzer rules. More information can be found in the documentation for the
-[UseCompatibleCmdlets][01] rule.
+This rule warns when a script defines a function that uses the name of a built-in cmdlet available
+for a target PowerShell version and operating system. Overwriting built-in cmdlet names can cause
+confusing behavior because callers might run your function when they expected the platform cmdlet.
 
-## Configuration
+The rule compares function declarations in your script against command allow lists that ship with
+PSScriptAnalyzer. The allow lists are also used by other compatibility rules. To learn more, see
+[UseCompatibleCmdlets][01].
 
-To enable the rule to check if your script is compatible on PowerShell Core on Windows, put the
-following your settings file.
+## Example
+
+### Noncompliant
+
+```powershell
+function Get-ChildItem {
+    param(
+        [string]$Path = '.'
+    )
+
+    "Custom listing for: $Path"
+}
+```
+
+### Compliant
+
+```powershell
+function Get-CustomChildItem {
+    param(
+        [string]$Path = '.'
+    )
+
+    Get-ChildItem -Path $Path
+}
+```
+
+## Configure rule
+
+To enable the rule to check if your script is compatible on PowerShell Core on Windows, add the
+following lines in your settings file.
 
 ```powershell
 @{
@@ -31,23 +59,26 @@ following your settings file.
 }
 ```
 
-### Parameters
-
-#### PowerShellVersion
+### PowerShellVersion
 
-The parameter `PowerShellVersion` is a list of allowlists that ship with PSScriptAnalyzer.
+The `PowerShellVersion` parameter accepts one or more command allow list names that ship with
+PSScriptAnalyzer. Set this value to the PowerShell version and platform you want to validate
+against.
 
 > [!NOTE]
-> The default value for `PowerShellVersion` is `core-6.1.0-windows` if PowerShell 6 or
-> later is installed, and `desktop-5.1.14393.206-windows` if it's not.
+> The default value for `PowerShellVersion` is `core-6.1.0-windows` if PowerShell 6 or later is
+installed, and `desktop-5.1.14393.206-windows` if it's not.
 
-Usually, patched versions of PowerShell have the same cmdlet data, therefore only settings of major
-and minor versions of PowerShell are supplied. One can also create a custom settings file as well
-with the [New-CommandDataFile.ps1][02] script and use it by placing the created `JSON` into the
-`Settings` folder of the `PSScriptAnalyzer` module installation folder, then the `PowerShellVersion`
-parameter is just its filename (that can also be changed if desired). Note that the `core-6.0.2-*`
-files were removed in PSScriptAnalyzer 1.18 since PowerShell 6.0 reached end of life.
+Patched PowerShell releases usually share the same cmdlet metadata, so the built-in allow lists are
+provided by major and minor version. You can also generate a custom allow list with
+[New-CommandDataFile.ps1][02]. To use a custom allow list, place the generated JSON file in the
+`Settings` folder of the PSScriptAnalyzer module installation path, then set `PowerShellVersion` to
+that filename.
+
+The `core-6.0.2-*` files were removed in PSScriptAnalyzer 1.18 because PowerShell 6.0 reached end of
+life.
 
 <!-- link references -->
-[01]: ./UseCompatibleCmdlets.md
+
+[01]: UseCompatibleCmdlets.md
 [02]: https://github.com/PowerShell/PSScriptAnalyzer/blob/main/Utils/New-CommandDataFile.ps1

reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidReservedWordsAsFunctionNames.md

@@ -1,6 +1,6 @@
 ---
 description: Avoid reserved words as function names
-ms.date: 08/31/2025
+ms.date: 06/01/2026
 ms.topic: reference
 title: AvoidReservedWordsAsFunctionNames
 ---
@@ -10,19 +10,14 @@ title: AvoidReservedWordsAsFunctionNames
 
 ## Description
 
-Avoid using reserved words as function names. Using reserved words as function names can cause
-errors or unexpected behavior in scripts.
-
-## How to Fix
-
-Avoid using any of the reserved words as function names. Choose a different name that's not a
-reserved word.
+Using reserved words as function names causes errors or unexpected behavior in PowerShell scripts.
+Choose function names that don't conflict with any PowerShell reserved words.
 
 See [about_Reserved_Words][01] for a list of reserved words in PowerShell.
 
 ## Example
 
-### Wrong
+### Noncompliant
 
 ```powershell
 # Function is a reserved word
@@ -31,7 +26,7 @@ function function {
 }
 ```
 
-### Correct
+### Compliant
 
 ```powershell
 # myFunction is not a reserved word
@@ -41,4 +36,5 @@ function myFunction {
 ```
 
 <!-- link references -->
+
 [01]: /powershell/module/microsoft.powershell.core/about/about_reserved_words