diff --git a/docs/Rules/AvoidExclaimOperator.md b/docs/Rules/AvoidExclaimOperator.md index 0eb4ff625..bafbc9d0e 100644 --- a/docs/Rules/AvoidExclaimOperator.md +++ b/docs/Rules/AvoidExclaimOperator.md @@ -1,11 +1,12 @@ --- description: Avoid exclaim operator ms.custom: PSSA v1.22.0 -ms.date: 02/13/2024 +ms.date: 03/26/2024 ms.topic: reference title: AvoidExclaimOperator --- # AvoidExclaimOperator + **Severity Level: Warning** ## Description @@ -19,13 +20,14 @@ Avoid using the negation operator (`!`). Use `-not` for improved readability. ## Example -### Wrong: +### Wrong ```powershell $MyVar = !$true ``` -### Correct: +### Correct + ```powershell $MyVar = -not $true ``` @@ -42,6 +44,6 @@ Rules = @{ ### Parameters -#### Enable: bool (Default value is `$false`) +- `Enable`: **bool** (Default value is `$false`) -Enable or disable the rule during ScriptAnalyzer invocation. \ No newline at end of file + Enable or disable the rule during ScriptAnalyzer invocation. diff --git a/docs/Rules/ProvideCommentHelp.md b/docs/Rules/ProvideCommentHelp.md index c6e373f36..51ef66df9 100644 --- a/docs/Rules/ProvideCommentHelp.md +++ b/docs/Rules/ProvideCommentHelp.md @@ -17,9 +17,9 @@ presence of comment based help and not on the validity or format. For assistance on comment based help, use the command `Get-Help about_comment_based_help` or the following articles: -- [Writing Comment-based Help](https://learn.microsoft.com/powershell/scripting/developer/help/writing-comment-based-help-topics) -- [Writing Help for PowerShell Cmdlets](https://learn.microsoft.com/powershell/scripting/developer/help/writing-help-for-windows-powershell-cmdlets) -- [Create XML-based help using PlatyPS](https://learn.microsoft.com/powershell/utility-modules/platyps/create-help-using-platyps) +- [Writing Comment-based Help][01] +- [Writing Help for PowerShell Cmdlets][02] +- [Create XML-based help using PlatyPS][03] ## Configuration @@ -37,34 +37,35 @@ Rules = @{ ### Parameters -#### Enable: bool (Default valus is `$true`) +- `Enable`: **bool** (Default valus is `$true`) -Enable or disable the rule during ScriptAnalyzer invocation. + Enable or disable the rule during ScriptAnalyzer invocation. -#### ExportedOnly: bool (Default value is `$true`) +- `ExportedOnly`: **bool** (Default value is `$true`) -If enabled, throw violation only on functions/cmdlets that are exported using the -`Export-ModuleMember` cmdlet. + If enabled, throw violation only on functions/cmdlets that are exported using the + `Export-ModuleMember` cmdlet. -#### BlockComment: bool (Default value is `$true`) +- `BlockComment`: **bool** (Default value is `$true`) -If enabled, returns comment help in block comment style, i.e., `<#...#>`. Otherwise returns comment -help in line comment style, i.e., each comment line starts with `#`. + If enabled, returns comment help in block comment style (`<#...#>`). Otherwise returns + comment help in line comment style where each comment line starts with `#`. -#### VSCodeSnippetCorrection: bool (Default value is `$false`) +- `VSCodeSnippetCorrection`: **bool** (Default value is `$false`) -If enabled, returns comment help in vscode snippet format. + If enabled, returns comment help in vscode snippet format. -#### Placement: string (Default value is `before`) +- `Placement`: **string** (Default value is `before`) -Represents the position of comment help with respect to the function definition. + Represents the position of comment help with respect to the function definition. -Possible values are: `before`, `begin` and `end`. If any invalid value is given, the property -defaults to `before`. + Possible values are: -`before` means the help is placed before the function definition. `begin` means the help is placed -at the beginning of the function definition body. `end` means the help is places the end of the -function definition body. + - `before`: means the help is placed before the function definition + - `begin` means the help is placed at the beginning of the function definition body + - `end` means the help is places the end of the function definition body + + If any invalid value is given, the property defaults to `before`. ## Example @@ -118,3 +119,7 @@ function Get-File } ``` + +[01]: https://learn.microsoft.com/powershell/scripting/developer/help/writing-comment-based-help-topics +[02]: https://learn.microsoft.com/powershell/scripting/developer/help/writing-help-for-windows-powershell-cmdlets +[03]: https://learn.microsoft.com/powershell/utility-modules/platyps/create-help-using-platyps diff --git a/docs/Rules/ReviewUnusedParameter.md b/docs/Rules/ReviewUnusedParameter.md index 1673bb5a3..6a4447785 100644 --- a/docs/Rules/ReviewUnusedParameter.md +++ b/docs/Rules/ReviewUnusedParameter.md @@ -1,7 +1,7 @@ --- description: ReviewUnusedParameter ms.custom: PSSA v1.22.0 -ms.date: 06/28/2023 +ms.date: 03/26/2024 ms.topic: reference title: ReviewUnusedParameter --- @@ -16,14 +16,14 @@ been used in that scope. ## Configuration settings -|Configuration key|Meaning|Accepted values|Mandatory|Example| -|---|---|---|---|---| -|CommandsToTraverse|By default, this command will not consider child scopes other than scriptblocks provided to Where-Object or ForEach-Object. This setting allows you to add additional commands that accept scriptblocks that this rule should traverse into.|string[]: list of commands whose scriptblock to traverse.|`@('Invoke-PSFProtectedCommand')`| +By default, this rule doesn't consider child scopes other than scriptblocks provided to +`Where-Object` or `ForEach-Object`. The `CommandsToTraverse` setting is an string array allows you +to add additional commands that accept scriptblocks that this rule should examine. ```powershell @{ Rules = @{ - ReviewUnusedParameter = @{ + PSReviewUnusedParameter = @{ CommandsToTraverse = @( 'Invoke-PSFProtectedCommand' ) diff --git a/docs/Rules/ShouldProcess.md b/docs/Rules/ShouldProcess.md index 6746c3621..38da8320e 100644 --- a/docs/Rules/ShouldProcess.md +++ b/docs/Rules/ShouldProcess.md @@ -18,9 +18,9 @@ but makes no calls to `ShouldProcess` or it calls `ShouldProcess` but does not d For more information, see the following articles: -- [about_Functions_Advanced_Methods](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_methods) -- [about_Functions_CmdletBindingAttribute](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_Functions_CmdletBindingAttribute) -- [Everything you wanted to know about ShouldProcess](https://learn.microsoft.com/powershell/scripting/learn/deep-dives/everything-about-shouldprocess) +- [about_Functions_Advanced_Methods][01] +- [about_Functions_CmdletBindingAttribute][02] +- [Everything you wanted to know about ShouldProcess][03] ## How @@ -73,3 +73,7 @@ function Set-File } } ``` + +[01]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_methods +[02]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_Functions_CmdletBindingAttribute +[03]: https://learn.microsoft.com/powershell/scripting/learn/deep-dives/everything-about-shouldprocess diff --git a/docs/Rules/UseApprovedVerbs.md b/docs/Rules/UseApprovedVerbs.md index f4d685585..858979574 100644 --- a/docs/Rules/UseApprovedVerbs.md +++ b/docs/Rules/UseApprovedVerbs.md @@ -1,7 +1,7 @@ --- description: Cmdlet Verbs ms.custom: PSSA v1.22.0 -ms.date: 06/28/2023 +ms.date: 03/26/2024 ms.topic: reference title: UseApprovedVerbs --- @@ -15,10 +15,9 @@ All cmdlets must used approved verbs. Approved verbs can be found by running the command `Get-Verb`. -Additional documentation on approved verbs can be found at -[Approved Verbs for PowerShell Commands](https://learn.microsoft.com/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands). -Some unapproved verbs are documented on the approved verbs page and point to approved alternatives. -Try searching for the verb you used to find its approved form. For example, searching for `Read`, +For a more information about approved verbs, see [Approved Verbs for PowerShell Commands][01]. Some +unapproved verbs are documented on the approved verbs page and point to approved alternatives. Try +searching for the verb you used to find its approved form. For example, searching for `Read`, `Open`, or `Search` leads you to `Get`. ## How @@ -44,3 +43,6 @@ function Update-Item ... } ``` + + +[01]: /powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands \ No newline at end of file diff --git a/docs/Rules/UseCompatibleCommands.md b/docs/Rules/UseCompatibleCommands.md index 6e0714f2f..dc8c06b97 100644 --- a/docs/Rules/UseCompatibleCommands.md +++ b/docs/Rules/UseCompatibleCommands.md @@ -102,7 +102,7 @@ An example configuration might look like: ```powershell @{ Rules = @{ - PSUseCompatibleCommmands = @{ + PSUseCompatibleCommands = @{ Enable = $true TargetProfiles = @( 'ubuntu_x64_18.04_6.1.3_x64_4.0.30319.42000_core' diff --git a/docs/Rules/UseSingularNouns.md b/docs/Rules/UseSingularNouns.md index e8d91677b..cde3b7028 100644 --- 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: 02/13/2024 +ms.date: 03/26/2024 ms.topic: reference title: UseSingularNouns --- @@ -11,9 +11,8 @@ title: UseSingularNouns ## Description -PowerShell team best practices state cmdlets should use singular nouns and not plurals. - -Suppression allows to suppress just specific function names, for example +PowerShell team best practices state cmdlets should use singular nouns and not plurals. Suppression +allows you to suppress the rule for specific function names. For example: ``` function Get-Elements { @@ -35,13 +34,14 @@ Rules = @{ ### Parameters -#### `UseSingularNouns: string[]` (Default value is `{'Data', 'Windows'}`) +- `UseSingularNouns`: `string[]` (Default value is `{'Data', 'Windows'}`) -Commands to be excluded from this rule. `Data` and `Windows` are common false positives and are excluded by default + Commands to be excluded from this rule. `Data` and `Windows` are common false positives and are + excluded by default. -#### Enable: `bool` (Default value is `$true`) +- `Enable`: `bool` (Default value is `$true`) -Enable or disable the rule during ScriptAnalyzer invocation. + Enable or disable the rule during ScriptAnalyzer invocation. ## How