diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidExclaimOperator.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidExclaimOperator.md index 0eb4ff6..bafbc9d 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidExclaimOperator.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/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/reference/docs-conceptual/PSScriptAnalyzer/Rules/ProvideCommentHelp.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/ProvideCommentHelp.md index 4e5d060..5042a0f 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/ProvideCommentHelp.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/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](/powershell/scripting/developer/help/writing-comment-based-help-topics) -- [Writing Help for PowerShell Cmdlets](/powershell/scripting/developer/help/writing-help-for-windows-powershell-cmdlets) -- [Create XML-based help using PlatyPS](../../platyps/create-help-using-platyps.md) +- [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]: /powershell/scripting/developer/help/writing-comment-based-help-topics +[02]: /powershell/scripting/developer/help/writing-help-for-windows-powershell-cmdlets +[03]: /powershell/utility-modules/platyps/create-help-using-platyps diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/ReviewUnusedParameter.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/ReviewUnusedParameter.md index fe95e2f..6a44477 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/ReviewUnusedParameter.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/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,9 +16,9 @@ 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 @{ diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/ShouldProcess.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/ShouldProcess.md index 8a089e4..a6ed5cb 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/ShouldProcess.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/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](/powershell/module/microsoft.powershell.core/about/about_functions_advanced_methods) -- [about_Functions_CmdletBindingAttribute](/powershell/module/microsoft.powershell.core/about/about_Functions_CmdletBindingAttribute) -- [Everything you wanted to know about ShouldProcess](/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]: /powershell/module/microsoft.powershell.core/about/about_functions_advanced_methods +[02]: /powershell/module/microsoft.powershell.core/about/about_Functions_CmdletBindingAttribute +[03]: /powershell/scripting/learn/deep-dives/everything-about-shouldprocess diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/UseApprovedVerbs.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/UseApprovedVerbs.md index 1207c9f..8589795 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/UseApprovedVerbs.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/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](/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/reference/docs-conceptual/PSScriptAnalyzer/Rules/UseSingularNouns.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/UseSingularNouns.md index e8d9167..cde3b70 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/UseSingularNouns.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/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