Update format and grammar of AvoidUsingAllowUnencryptedAuthentication (…

…PowerShell#1974) * Update format and grammar of AvoidUsingAllowUnencryptedAuthentication * Syncing docs changes to all rules * Update rules to match docs and improve wording
sdwheeler · Mar 13, 2024 · 03b655c · 03b655c
1 parent b4365ad
commit 03b655c
Show file tree

Hide file tree

Showing 7 changed files with 39 additions and 22 deletions.
diff --git a/docs/Rules/AvoidExclaimOperator.md b/docs/Rules/AvoidExclaimOperator.md
@@ -1,7 +1,7 @@
 ---
 description: Avoid exclaim operator
 ms.custom: PSSA v1.22.0
-ms.date: 06/14/2023
+ms.date: 02/13/2024
 ms.topic: reference
 title: AvoidExclaimOperator
 ---
@@ -10,20 +10,23 @@ title: AvoidExclaimOperator
 
 ## Description
 
-The negation operator `!` should not be used for readability purposes. Use `-not` instead.
+Avoid using the negation operator (`!`). Use `-not` for improved readability.
 
-**Note**: This rule is not enabled by default. The user needs to enable it through settings.
+> [!NOTE]
+> This rule is not enabled by default. The user needs to enable it through settings.
 
 ## How to Fix
 
 ## Example
+
 ### Wrong：
-```PowerShell
+
+```powershell
 $MyVar = !$true
 ```
 
 ### Correct:
-```PowerShell
+```powershell
 $MyVar = -not $true
 ```
 

diff --git a/docs/Rules/AvoidUsingAllowUnencryptedAuthentication.md b/docs/Rules/AvoidUsingAllowUnencryptedAuthentication.md
@@ -1,7 +1,7 @@
 ---
 description: Avoid sending credentials and secrets over unencrypted connections
 ms.custom: PSSA v1.22.0
-ms.date: 11/06/2022
+ms.date: 02/28/2024
 ms.topic: reference
 title: AvoidUsingAllowUnencryptedAuthentication
 ---
@@ -11,14 +11,15 @@ title: AvoidUsingAllowUnencryptedAuthentication
 
 ## Description
 
-Avoid using the `AllowUnencryptedAuthentication` switch on `Invoke-WebRequest`, `Invoke-RestMethod`, and other webrequest cmdlets, which sends credentials and secrets over unencrypted connections.
-This should be avoided except for compatability with legacy systems.
+Avoid using the **AllowUnencryptedAuthentication** parameter of `Invoke-WebRequest` and
+`Invoke-RestMethod`. When using this parameter, the cmdlets send credentials and secrets over
+unencrypted connections. This should be avoided except for compatibility with legacy systems.
 
-For more details, see the documentation warning [here](https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/invoke-webrequest#-allowunencryptedauthentication).
+For more details, see [Invoke-RestMethod](xref:Microsoft.PowerShell.Utility.Invoke-RestMethod).
 
 ## How
 
-Avoid using the `AllowUnencryptedAuthentication` switch.
+Avoid using the **AllowUnencryptedAuthentication** parameter.
 
 ## Example 1
 
@@ -32,4 +33,4 @@ Invoke-WebRequest foo -AllowUnencryptedAuthentication
 
 ```powershell
 Invoke-WebRequest foo
-```
+```
diff --git a/docs/Rules/AvoidUsingPositionalParameters.md b/docs/Rules/AvoidUsingPositionalParameters.md
@@ -1,7 +1,7 @@
 ---
 description: Avoid Using Positional Parameters
 ms.custom: PSSA v1.22.0
-ms.date: 06/28/2023
+ms.date: 02/13/2024
 ms.topic: reference
 title: AvoidUsingPositionalParameters
 ---

diff --git a/docs/Rules/README.md b/docs/Rules/README.md
@@ -1,7 +1,7 @@
 ---
 description: List of PSScriptAnalyzer rules
 ms.custom: PSSA v1.22.0
-ms.date: 06/28/2023
+ms.date: 02/13/2024
 ms.topic: reference
 title: List of PSScriptAnalyzer rules
 ---

diff --git a/docs/Rules/ReservedParams.md b/docs/Rules/ReservedParams.md
@@ -1,7 +1,7 @@
 ---
 description: Reserved Parameters
 ms.custom: PSSA v1.22.0
-ms.date: 06/28/2023
+ms.date: 03/06/2024
 ms.topic: reference
 title: ReservedParams
 ---
@@ -11,9 +11,9 @@ title: ReservedParams
 
 ## Description
 
-You cannot use [reserved common parameters][01] in an advanced function.
-
-[01]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_commonparameters
+You can't redefine [common parameters][01] in an advanced function. Using the `CmdletBinding` or
+`Parameter` attributes creates an advanced function. The common parameters are are automatically
+available in advanced functions, so you can't redefine them.
 
 ## How
 
@@ -48,3 +48,5 @@ function Test
     )
 }
 ```
+
+[01]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_commonparameters
diff --git a/docs/Rules/UseDeclaredVarsMoreThanAssignments.md b/docs/Rules/UseDeclaredVarsMoreThanAssignments.md
@@ -1,7 +1,7 @@
 ---
 description: Extra Variables
 ms.custom: PSSA v1.22.0
-ms.date: 06/28/2023
+ms.date: 03/06/2024
 ms.topic: reference
 title: UseDeclaredVarsMoreThanAssignments
 ---
@@ -44,10 +44,13 @@ function Test
 }
 ```
 
-### Special case
+### Special cases
 
-The following example triggers the **PSUseDeclaredVarsMoreThanAssignments** warning because `$bar`
-is not used within the scriptblock where it was defined.
+The following examples trigger the **PSUseDeclaredVarsMoreThanAssignments** warning. This behavior
+is a limitation of the rule. There is no way to avoid these false positive warnings.
+
+In this case, the warning is triggered because `$bar` is not used within the scriptblock where it
+was defined.
 
 ```powershell
 $foo | ForEach-Object {
@@ -60,3 +63,11 @@ if($bar){
     Write-Host 'Collection contained a false case.'
 }
 ```
+
+In the next example, the warning is triggered because `$errResult` isn't recognized as being used in
+the `Write-Host` command.
+
+```powershell
+$errResult = $null
+Write-Host 'Ugh:' -ErrorVariable errResult
+```
diff --git a/docs/Rules/UseSingularNouns.md b/docs/Rules/UseSingularNouns.md
@@ -1,7 +1,7 @@
 ---
 description: Cmdlet Singular Noun
 ms.custom: PSSA v1.22.0
-ms.date: 06/28/2023
+ms.date: 02/13/2024
 ms.topic: reference
 title: UseSingularNouns
 ---