Skip to content

Commit a0365a5

Browse files
sdwheelersdwheeler
authored
Sync rule docs changes (#1985)
1 parent 62a14c5 commit a0365a5

7 files changed

+60
-47
lines changed

‎docs/Rules/AvoidExclaimOperator.md

+7-5
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
---
22
description: Avoid exclaim operator
33
ms.custom: PSSA v1.22.0
4-
ms.date: 02/13/2024
4+
ms.date: 03/26/2024
55
ms.topic: reference
66
title: AvoidExclaimOperator
77
---
88
# AvoidExclaimOperator
9+
910
**Severity Level: Warning**
1011

1112
## Description
@@ -19,13 +20,14 @@ Avoid using the negation operator (`!`). Use `-not` for improved readability.
1920

2021
## Example
2122

22-
### Wrong：
23+
### Wrong
2324

2425
```powershell
2526
$MyVar = !$true
2627
```
2728

28-
### Correct:
29+
### Correct
30+
2931
```powershell
3032
$MyVar = -not $true
3133
```
@@ -42,6 +44,6 @@ Rules = @{
4244

4345
### Parameters
4446

45-
#### Enable: bool (Default value is `$false`)
47+
- `Enable`: **bool** (Default value is `$false`)
4648

47-
Enable or disable the rule during ScriptAnalyzer invocation.
49+
Enable or disable the rule during ScriptAnalyzer invocation.

‎docs/Rules/ProvideCommentHelp.md

+25-20
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,9 @@ presence of comment based help and not on the validity or format.
1717
For assistance on comment based help, use the command `Get-Help about_comment_based_help` or the
1818
following articles:
1919

20-
- [Writing Comment-based Help](https://learn.microsoft.com/powershell/scripting/developer/help/writing-comment-based-help-topics)
21-
- [Writing Help for PowerShell Cmdlets](https://learn.microsoft.com/powershell/scripting/developer/help/writing-help-for-windows-powershell-cmdlets)
22-
- [Create XML-based help using PlatyPS](https://learn.microsoft.com/powershell/utility-modules/platyps/create-help-using-platyps)
20+
- [Writing Comment-based Help][01]
21+
- [Writing Help for PowerShell Cmdlets][02]
22+
- [Create XML-based help using PlatyPS][03]
2323

2424
## Configuration
2525

@@ -37,34 +37,35 @@ Rules = @{
3737

3838
### Parameters
3939

40-
#### Enable: bool (Default valus is `$true`)
40+
- `Enable`: **bool** (Default valus is `$true`)
4141

42-
Enable or disable the rule during ScriptAnalyzer invocation.
42+
Enable or disable the rule during ScriptAnalyzer invocation.
4343

44-
#### ExportedOnly: bool (Default value is `$true`)
44+
- `ExportedOnly`: **bool** (Default value is `$true`)
4545

46-
If enabled, throw violation only on functions/cmdlets that are exported using the
47-
`Export-ModuleMember` cmdlet.
46+
If enabled, throw violation only on functions/cmdlets that are exported using the
47+
`Export-ModuleMember` cmdlet.
4848

49-
#### BlockComment: bool (Default value is `$true`)
49+
- `BlockComment`: **bool** (Default value is `$true`)
5050

51-
If enabled, returns comment help in block comment style, i.e., `<#...#>`. Otherwise returns comment
52-
help in line comment style, i.e., each comment line starts with `#`.
51+
If enabled, returns comment help in block comment style (`<#...#>`). Otherwise returns
52+
comment help in line comment style where each comment line starts with `#`.
5353

54-
#### VSCodeSnippetCorrection: bool (Default value is `$false`)
54+
- `VSCodeSnippetCorrection`: **bool** (Default value is `$false`)
5555

56-
If enabled, returns comment help in vscode snippet format.
56+
If enabled, returns comment help in vscode snippet format.
5757

58-
#### Placement: string (Default value is `before`)
58+
- `Placement`: **string** (Default value is `before`)
5959

60-
Represents the position of comment help with respect to the function definition.
60+
Represents the position of comment help with respect to the function definition.
6161

62-
Possible values are: `before`, `begin` and `end`. If any invalid value is given, the property
63-
defaults to `before`.
62+
Possible values are:
6463

65-
`before` means the help is placed before the function definition. `begin` means the help is placed
66-
at the beginning of the function definition body. `end` means the help is places the end of the
67-
function definition body.
64+
- `before`: means the help is placed before the function definition
65+
- `begin` means the help is placed at the beginning of the function definition body
66+
- `end` means the help is places the end of the function definition body
67+
68+
If any invalid value is given, the property defaults to `before`.
6869

6970
## Example
7071

@@ -118,3 +119,7 @@ function Get-File
118119
119120
}
120121
```
122+
<!-- link references -->
123+
[01]: https://learn.microsoft.com/powershell/scripting/developer/help/writing-comment-based-help-topics
124+
[02]: https://learn.microsoft.com/powershell/scripting/developer/help/writing-help-for-windows-powershell-cmdlets
125+
[03]: https://learn.microsoft.com/powershell/utility-modules/platyps/create-help-using-platyps

‎docs/Rules/ReviewUnusedParameter.md

+5-5
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description: ReviewUnusedParameter
33
ms.custom: PSSA v1.22.0
4-
ms.date: 06/28/2023
4+
ms.date: 03/26/2024
55
ms.topic: reference
66
title: ReviewUnusedParameter
77
---
@@ -16,14 +16,14 @@ been used in that scope.
1616

1717
## Configuration settings
1818

19-
|Configuration key|Meaning|Accepted values|Mandatory|Example|
20-
|---|---|---|---|---|
21-
|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')`|
19+
By default, this rule doesn't consider child scopes other than scriptblocks provided to
20+
`Where-Object` or `ForEach-Object`. The `CommandsToTraverse` setting is an string array allows you
21+
to add additional commands that accept scriptblocks that this rule should examine.
2222

2323
```powershell
2424
@{
2525
Rules = @{
26-
ReviewUnusedParameter = @{
26+
PSReviewUnusedParameter = @{
2727
CommandsToTraverse = @(
2828
'Invoke-PSFProtectedCommand'
2929
)

‎docs/Rules/ShouldProcess.md

+7-3
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,9 @@ but makes no calls to `ShouldProcess` or it calls `ShouldProcess` but does not d
1818

1919
For more information, see the following articles:
2020

21-
- [about_Functions_Advanced_Methods](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_methods)
22-
- [about_Functions_CmdletBindingAttribute](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_Functions_CmdletBindingAttribute)
23-
- [Everything you wanted to know about ShouldProcess](https://learn.microsoft.com/powershell/scripting/learn/deep-dives/everything-about-shouldprocess)
21+
- [about_Functions_Advanced_Methods][01]
22+
- [about_Functions_CmdletBindingAttribute][02]
23+
- [Everything you wanted to know about ShouldProcess][03]
2424

2525
## How
2626

@@ -73,3 +73,7 @@ function Set-File
7373
}
7474
}
7575
```
76+
<!-- link references -->
77+
[01]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_methods
78+
[02]: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_Functions_CmdletBindingAttribute
79+
[03]: https://learn.microsoft.com/powershell/scripting/learn/deep-dives/everything-about-shouldprocess

‎docs/Rules/UseApprovedVerbs.md

+7-5
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description: Cmdlet Verbs
33
ms.custom: PSSA v1.22.0
4-
ms.date: 06/28/2023
4+
ms.date: 03/26/2024
55
ms.topic: reference
66
title: UseApprovedVerbs
77
---
@@ -15,10 +15,9 @@ All cmdlets must used approved verbs.
1515

1616
Approved verbs can be found by running the command `Get-Verb`.
1717

18-
Additional documentation on approved verbs can be found at
19-
[Approved Verbs for PowerShell Commands](https://learn.microsoft.com/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands).
20-
Some unapproved verbs are documented on the approved verbs page and point to approved alternatives.
21-
Try searching for the verb you used to find its approved form. For example, searching for `Read`,
18+
For a more information about approved verbs, see [Approved Verbs for PowerShell Commands][01]. Some
19+
unapproved verbs are documented on the approved verbs page and point to approved alternatives. Try
20+
searching for the verb you used to find its approved form. For example, searching for `Read`,
2221
`Open`, or `Search` leads you to `Get`.
2322

2423
## How
@@ -44,3 +43,6 @@ function Update-Item
4443
...
4544
}
4645
```
46+
47+
<!-- link references -->
48+
[01]: /powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands

‎docs/Rules/UseCompatibleCommands.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ An example configuration might look like:
102102
```powershell
103103
@{
104104
Rules = @{
105-
PSUseCompatibleCommmands = @{
105+
PSUseCompatibleCommands = @{
106106
Enable = $true
107107
TargetProfiles = @(
108108
'ubuntu_x64_18.04_6.1.3_x64_4.0.30319.42000_core'

‎docs/Rules/UseSingularNouns.md

+8-8
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description: Cmdlet Singular Noun
33
ms.custom: PSSA v1.22.0
4-
ms.date: 02/13/2024
4+
ms.date: 03/26/2024
55
ms.topic: reference
66
title: UseSingularNouns
77
---
@@ -11,9 +11,8 @@ title: UseSingularNouns
1111

1212
## Description
1313

14-
PowerShell team best practices state cmdlets should use singular nouns and not plurals.
15-
16-
Suppression allows to suppress just specific function names, for example
14+
PowerShell team best practices state cmdlets should use singular nouns and not plurals. Suppression
15+
allows you to suppress the rule for specific function names. For example:
1716

1817
```
1918
function Get-Elements {
@@ -35,13 +34,14 @@ Rules = @{
3534

3635
### Parameters
3736

38-
#### `UseSingularNouns: string[]` (Default value is `{'Data', 'Windows'}`)
37+
- `UseSingularNouns`: `string[]` (Default value is `{'Data', 'Windows'}`)
3938

40-
Commands to be excluded from this rule. `Data` and `Windows` are common false positives and are excluded by default
39+
Commands to be excluded from this rule. `Data` and `Windows` are common false positives and are
40+
excluded by default.
4141

42-
#### Enable: `bool` (Default value is `$true`)
42+
- `Enable`: `bool` (Default value is `$true`)
4343

44-
Enable or disable the rule during ScriptAnalyzer invocation.
44+
Enable or disable the rule during ScriptAnalyzer invocation.
4545

4646
## How
4747

0 commit comments

Comments
 (0)