Updates to comment help and examples (#2196)

src/Main.ps1

@@ -14,37 +14,32 @@ function Assert-ValidAssertionAlias {
 
 function Add-ShouldOperator {
     <#
-.SYNOPSIS
+    .SYNOPSIS
     Register a Should Operator with Pester
-.DESCRIPTION
+    .DESCRIPTION
     This function allows you to create custom Should assertions.
-.PARAMETER Name
+    .PARAMETER Name
     The name of the assertion. This will become a Named Parameter of Should.
-.PARAMETER Test
+    .PARAMETER Test
     The test function. The function must return a PSObject with a [Bool]succeeded and a [string]failureMessage property.
-.PARAMETER Alias
+    .PARAMETER Alias
     A list of aliases for the Named Parameter.
-.PARAMETER SupportsArrayInput
+    .PARAMETER SupportsArrayInput
     Does the test function support the passing an array of values to test.
-.PARAMETER InternalName
+    .PARAMETER InternalName
     If -Name is different from the actual function name, record the actual function name here.
     Used by Get-ShouldOperator to pull function help.
-.EXAMPLE
+    .EXAMPLE
     ```powershell
-    function BeAwesome($ActualValue, [switch] $Negate)
-    {
-
+    function BeAwesome($ActualValue, [switch] $Negate) {
         [bool] $succeeded = $ActualValue -eq 'Awesome'
         if ($Negate) { $succeeded = -not $succeeded }
 
-        if (-not $succeeded)
-        {
-            if ($Negate)
-            {
+        if (-not $succeeded) {
+            if ($Negate) {
                 $failureMessage = "{$ActualValue} is Awesome"
             }
-            else
-            {
+            else {
                 $failureMessage = "{$ActualValue} is not Awesome"
             }
         }
@@ -55,16 +50,18 @@ function Add-ShouldOperator {
         }
     }
 
-    Add-ShouldOperator -Name  BeAwesome `
-                        -Test  $function:BeAwesome `
-                        -Alias 'BA'
+    Add-ShouldOperator -Name BeAwesome `
+        -Test $function:BeAwesome `
+        -Alias 'BA'
 
-    PS C:\> "bad" | should -BeAwesome
+    PS C:\> "bad" | Should -BeAwesome
     {bad} is not Awesome
     ```
-.LINK
+
+    Example of how to create a simple custom assertion that checks if the input string is 'Awesome'
+    .LINK
     https://pester.dev/docs/commands/Add-ShouldOperator
-#>
+    #>
     [CmdletBinding()]
     param (
         [Parameter(Mandatory = $true)]
@@ -1279,7 +1276,6 @@ function New-PesterOption {
     .LINK
     Invoke-Pester
     #>
-
     [CmdletBinding()]
     param (
         [switch] $IncludeVSCodeMarker,

src/Pester.RSpec.ps1

@@ -463,8 +463,6 @@ function New-PesterConfiguration {
 
     .LINK
     https://pester.dev/docs/commands/Invoke-Pester
-
-
     #>
     [CmdletBinding()]
     param(

src/functions/Context.ps1

@@ -1,70 +1,73 @@
 function Context {
     <#
-.SYNOPSIS
-Provides logical grouping of It blocks within a single Describe block.
-
-.DESCRIPTION
-Provides logical grouping of It blocks within a single Describe block.
-Any Mocks defined inside a Context are removed at the end of the Context scope,
-as are any files or folders added to the TestDrive during the Context block's
-execution. Any BeforeEach or AfterEach blocks defined inside a Context also only
-apply to tests within that Context .
-
-.PARAMETER Name
-The name of the Context. This is a phrase describing a set of tests within a describe.
-
-.PARAMETER Tag
-Optional parameter containing an array of strings. When calling Invoke-Pester,
-it is possible to specify a -Tag parameter which will only execute Context blocks
-containing the same Tag.
-
-.PARAMETER Fixture
-Script that is executed. This may include setup specific to the context
-and one or more It blocks that validate the expected outcomes.
-
-.PARAMETER ForEach
-Allows data driven tests to be written.
-Takes an array of data and generates one block for each item in the array, and makes the item
-available as $_ in all child blocks. When the array is an array of hashtables, it additionally
-defines each key in the hashatble as variable.
-
-.EXAMPLE
-```powershell
-function Add-Numbers($a, $b) {
-    return $a + $b
-}
-
-Describe "Add-Numbers" {
-    Context "when root does not exist" {
-        It "..." {
-            # ...
+    .SYNOPSIS
+    Provides logical grouping of It blocks within a single Describe block.
+
+    .DESCRIPTION
+    Provides logical grouping of It blocks within a single Describe block.
+    Any Mocks defined inside a Context are removed at the end of the Context scope,
+    as are any files or folders added to the TestDrive during the Context block's
+    execution. Any BeforeEach or AfterEach blocks defined inside a Context also only
+    apply to tests within that Context .
+
+    .PARAMETER Name
+    The name of the Context. This is a phrase describing a set of tests within a describe.
+
+    .PARAMETER Tag
+    Optional parameter containing an array of strings. When calling Invoke-Pester,
+    it is possible to specify a -Tag parameter which will only execute Context blocks
+    containing the same Tag.
+
+    .PARAMETER Fixture
+    Script that is executed. This may include setup specific to the context
+    and one or more It blocks that validate the expected outcomes.
+
+    .PARAMETER ForEach
+    Allows data driven tests to be written.
+    Takes an array of data and generates one block for each item in the array, and makes the item
+    available as $_ in all child blocks. When the array is an array of hashtables, it additionally
+    defines each key in the hashatble as variable.
+
+    .EXAMPLE
+    ```powershell
+    BeforeAll {
+        function Add-Numbers($a, $b) {
+            return $a + $b
         }
     }
 
-    Context "when root does exist" {
-        It "..." {
-            # ...
+    Describe 'Add-Numbers' {
+        Context 'when adding positive values' {
+            It '...' {
+                # ...
+            }
         }
-        It "..." {
-            # ...
+
+        Context 'when adding negative values' {
+            It '...' {
+                # ...
+            }
+            It '...' {
+                # ...
+            }
         }
     }
-}
-```
+    ```
 
-.LINK
-https://pester.dev/docs/commands/Context
+    Example of how to use Context for grouping different tests
 
-.LINK
-https://pester.dev/docs/usage/test-file-structure
+    .LINK
+    https://pester.dev/docs/commands/Context
 
-.LINK
-https://pester.dev/docs/usage/mocking
+    .LINK
+    https://pester.dev/docs/usage/test-file-structure
 
-.LINK
-https://pester.dev/docs/usage/testdrive
+    .LINK
+    https://pester.dev/docs/usage/mocking
 
-#>
+    .LINK
+    https://pester.dev/docs/usage/testdrive
+    #>
     param(
         [Parameter(Mandatory = $true, Position = 0)]
         [string] $Name,

src/functions/Describe.ps1

@@ -1,76 +1,80 @@
 function Describe {
     <#
-.SYNOPSIS
-Creates a logical group of tests.
-
-.DESCRIPTION
-Creates a logical group of tests. All Mocks, TestDrive and TestRegistry contents
-defined within a Describe block are scoped to that Describe; they
-will no longer be present when the Describe block exits.  A Describe
-block may contain any number of Context and It blocks.
-
-.PARAMETER Name
-The name of the test group. This is often an expressive phrase describing
-the scenario being tested.
-
-.PARAMETER Fixture
-The actual test script. If you are following the AAA pattern (Arrange-Act-Assert),
-this typically holds the arrange and act sections. The Asserts will also lie
-in this block but are typically nested each in its own It block. Assertions are
-typically performed by the Should command within the It blocks.
-
-.PARAMETER Tag
-Optional parameter containing an array of strings. When calling Invoke-Pester,
-it is possible to specify a -Tag parameter which will only execute Describe blocks
-containing the same Tag.
-
-.PARAMETER ForEach
-Allows data driven tests to be written.
-Takes an array of data and generates one block for each item in the array, and makes the item
-available as $_ in all child blocks. When the array is an array of hashtables, it additionally
-defines each key in the hashatble as variable.
-
-.EXAMPLE
-```powershell
-function Add-Numbers($a, $b) {
-    return $a + $b
-}
-
-Describe "Add-Numbers" {
-    It "adds positive numbers" {
-        $sum = Add-Numbers 2 3
-        $sum | Should -Be 5
+    .SYNOPSIS
+    Creates a logical group of tests.
+
+    .DESCRIPTION
+    Creates a logical group of tests. All Mocks, TestDrive and TestRegistry contents
+    defined within a Describe block are scoped to that Describe; they
+    will no longer be present when the Describe block exits.  A Describe
+    block may contain any number of Context and It blocks.
+
+    .PARAMETER Name
+    The name of the test group. This is often an expressive phrase describing
+    the scenario being tested.
+
+    .PARAMETER Fixture
+    The actual test script. If you are following the AAA pattern (Arrange-Act-Assert),
+    this typically holds the arrange and act sections. The Asserts will also lie
+    in this block but are typically nested each in its own It block. Assertions are
+    typically performed by the Should command within the It blocks.
+
+    .PARAMETER Tag
+    Optional parameter containing an array of strings. When calling Invoke-Pester,
+    it is possible to specify a -Tag parameter which will only execute Describe blocks
+    containing the same Tag.
+
+    .PARAMETER ForEach
+    Allows data driven tests to be written.
+    Takes an array of data and generates one block for each item in the array, and makes the item
+    available as $_ in all child blocks. When the array is an array of hashtables, it additionally
+    defines each key in the hashatble as variable.
+
+    .EXAMPLE
+    ```powershell
+    BeforeAll {
+        function Add-Numbers($a, $b) {
+            return $a + $b
+        }
     }
 
-    It "adds negative numbers" {
-        $sum = Add-Numbers (-2) (-2)
-        $sum | Should -Be (-4)
-    }
+    Describe "Add-Numbers" {
+        It "adds positive numbers" {
+            $sum = Add-Numbers 2 3
+            $sum | Should -Be 5
+        }
 
-    It "adds one negative number to positive number" {
-        $sum = Add-Numbers (-2) 2
-        $sum | Should -Be 0
-    }
+        It "adds negative numbers" {
+            $sum = Add-Numbers (-2) (-2)
+            $sum | Should -Be (-4)
+        }
+
+        It "adds one negative number to positive number" {
+            $sum = Add-Numbers (-2) 2
+            $sum | Should -Be 0
+        }
 
-    It "concatenates strings if given strings" {
-        $sum = Add-Numbers two three
-        $sum | Should -Be "twothree"
+        It "concatenates strings if given strings" {
+            $sum = Add-Numbers two three
+            $sum | Should -Be "twothree"
+        }
     }
-}
-```
+    ```
+
+    Using Describe to group tests logically at the root of the script/container
 
-.LINK
-https://pester.dev/docs/commands/Describe
+    .LINK
+    https://pester.dev/docs/commands/Describe
 
-.LINK
-https://pester.dev/docs/usage/test-file-structure
+    .LINK
+    https://pester.dev/docs/usage/test-file-structure
 
-.LINK
-https://pester.dev/docs/usage/mocking
+    .LINK
+    https://pester.dev/docs/usage/mocking
 
-.LINK
-https://pester.dev/docs/usage/testdrive
-#>
+    .LINK
+    https://pester.dev/docs/usage/testdrive
+    #>
 
     param(
         [Parameter(Mandatory = $true, Position = 0)]

src/functions/Get-ShouldOperator.ps1

@@ -32,7 +32,6 @@
 
     .LINK
     https://pester.dev/docs/commands/Should
-
     #>
     [CmdletBinding()]
     param ()

src/functions/In.ps1

@@ -12,12 +12,11 @@
     .PARAMETER Path
     The path that the execute block will be executed in.
 
-    .PARAMETER execute
+    .PARAMETER ScriptBlock
     The script to be executed in the path provided.
 
     .LINK
     https://github.com/pester/Pester/wiki/In
-
     #>
     [CmdletBinding(DefaultParameterSetName = "Default")]
     param(