Fix should help examples

BUILD.md

@@ -1,13 +1,64 @@
-## Building Pester
+# Building Pester
 
-Pester has a C# Solution which requires .Net Framework SDKs and Developer Packs in order to compile. The targetted frameworks can be found in `src\csharp\Pester\Pester.csproj`.
+Pester is written in Powershell and C#.  The Microsoft .NET Framework 4.5.2 is required to build the Pester binaries.
 
-### Required Software
+Pester has a C# Solution which requires .NET Framework SDKs and Developer Packs in order to compile. The targeted frameworks can be found in `src\csharp\Pester\Pester.csproj`.
 
-#### Install .NET Core 3.1 SDK
+## Required Software
+
+### Install .NET Core 3.1 SDK
 
 [Download Link](https://dotnet.microsoft.com/download/dotnet-core/3.1)
 
-#### .Net Framework 4.5 Developer Pack
+### .Net Framework 4.5 Developer Pack
 
 [Download Link](https://dotnet.microsoft.com/download/dotnet-framework/net452)
+<https://aka.ms/msbuild/developerpacks>
+
+## Running Tests
+
+In Powershell, run test.ps1.  This defines the inherited function InPesterModuleScope and some types required for the tests.
+
+Afterwards, each test can be run individually using Invoke-Pester.
+
+Test.ps1 and optionally -skipPTests to skip the .ts.ps1 files.
+
+## test.ps1
+
+test.ps1 can be run with the following parameters:
+
+```powershell
+.\test.ps1 -CI -SkipPTests -NoBuild -File ${filename}
+```
+
+### Test Parameters
+
+```powershell
+.PARAMETER CI
+  Exits after run.  Enables test results and code coverage on /src/*. Enable exit with 1 if tests don't pass. Forces P Tests to fail when dt is left in the tests. dt only runs the specified test, so leaving it in code would run only one test from the file on the server. 
+.PARAMETER SkipPTests
+  Skips Passthrough P tests. Skip the tests written using the P module, Unit Tests for the Runtime, and Acceptance Tests for Pester
+.NoBuild
+  Skips running build.ps1. Do not build the underlying csharp components. Used in CI pipeline since a clean build has already been run prior to Test.
+.File
+  If specified, set file path to test file, otherwise set to /tst folder. Pass the file to run Pester (not P) tests from.
+  */demo/*, */examples/*, */testProjects/* are excluded from tests.
+```
+
+Tests are excluded with Tags VersionChecks, StyleRules, Help.
+
+## Continuous Integration
+
+The Azure Devops Pipeline azure-pipelines.yml file contains the code definition used for builds, unit and integration tests in the CI pipeline.
+
+Within the pipeline, tests are executed against PS7 Core on a strategy matrix of machines, including Ubuntu 16.04, 18.04, macOS Mojave 10.14, Catalina 10.15, Windows Server 2016, 2019. Tests are also executed against PS6.2, PS4, PS3.
+
+## Documentation
+
+Documentation is available in the repo, the [Pester wiki](https://github.com/pester/Pester/wiki), and at <https://pester.dev>
+
+Documentation is written in Markdown. Comment-based Documentation and parts of the documentation web site are generated using Docusaurus Powershell.
+
+Multi-line examples added to comments should use fenced code.
+
+<https://docusaurus-powershell.netlify.app/docs/faq/multi-line-examples>

src/Pester.ps1

@@ -18,6 +18,17 @@ function Add-ShouldOperator {
     Register a Should Operator with Pester
 .DESCRIPTION
     This function allows you to create custom Should assertions.
+.PARAMETER Name
+    The name of the assertion. This will become a Named Parameter of Should.
+.PARAMETER Test
+    The test function. The function must return a PSObject with a [Bool]succeeded and a [string]failureMessage property.
+.PARAMETER Alias
+    A list of aliases for the Named Parameter.
+.PARAMETER SupportsArrayInput
+    Does the test function support the passing an array of values to test.
+.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
     function BeAwesome($ActualValue, [switch] $Negate)
     {
@@ -49,17 +60,6 @@ function Add-ShouldOperator {
 
     PS C:\> "bad" | should -BeAwesome
     {bad} is not Awesome
-.PARAMETER Name
-    The name of the assertion. This will become a Named Parameter of Should.
-.PARAMETER Test
-    The test function. The function must return a PSObject with a [Bool]succeeded and a [string]failureMessage property.
-.PARAMETER Alias
-    A list of aliases for the Named Parameter.
-.PARAMETER SupportsArrayInput
-    Does the test function support the passing an array of values to test.
-.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.
 #>
     [CmdletBinding()]
     param (

src/functions/Describe.ps1

@@ -57,12 +57,28 @@ Describe "Add-Numbers" {
     }
 }
 
+.LINK
+https://pester.dev/docs/commands/Describe
+
+.LINK
+https://github.com/pester/Pester/wiki/Describe
+
 .LINK
 It
+
+.LINK
 Context
+
+.LINK
 Invoke-Pester
+
+.LINK
 about_Should
+
+.LINK
 about_Mocking
+
+.LINK
 about_TestDrive
 
 #>

src/functions/New-MockObject.ps1

@@ -17,6 +17,13 @@ $obj = New-MockObject -Type 'System.Diagnostics.Process'
 $obj.GetType().FullName
     System.Diagnostics.Process
 ```
+
+.LINK
+https://pester.dev/docs/commands/New-MockObject
+
+.LINK
+https://pester.dev/docs/usage/mocking
+
 #>
 
     param (

src/functions/assertions/Should.ps1

@@ -22,23 +22,86 @@ function New-ShouldErrorRecord ([string] $Message, [string] $File, [string] $Lin
 function Should {
     <#
     .SYNOPSIS
-    Should is a keyword what is used to define an assertion inside It block.
+    Should is a keyword that is used to define an assertion inside an It block.
 
     .DESCRIPTION
-    Should is a keyword what is used to define an assertion inside the It block.
-    Should provides assertion methods for verify assertion e.g. comparing objects.
-    If assertion is not met the test fails and an exception is throwed up.
+    Should is a keyword that is used to define an assertion inside an It block.
+    Should provides assertion methods to verify assertions e.g. comparing objects.
+    If assertion is not met the test fails and an exception is thrown.
 
     Should can be used more than once in the It block if more than one assertion
-    need to be verified. Each Should keywords need to be located in a new line.
+    need to be verified. Each Should keyword needs to be on a separate line.
     Test will be passed only when all assertion will be met (logical conjuction).
 
     .LINK
-    https://github.com/pester/Pester/wiki/Should
+    https://pester.dev/docs/usage/assertions
 
     .LINK
     about_Should
+
+    .LINK
     about_Pester
+
+    .EXAMPLE
+    ```ps
+    Describe "d1" {
+        BeforeEach { $be = 1 }
+        It "i1" {
+            $be = 2
+        }
+        AfterEach { Write-Host "AfterEach: $be" }
+    }
+    ```
+
+    .EXAMPLE
+    ```ps
+    Describe "d1" {
+        It "i1" {
+            $user = Get-User
+            $user | Should -NotBeNullOrEmpty -ErrorAction Stop
+            $user |
+                Should -HaveProperty Name -Value "Jakub" |
+                Should -HaveProperty Age  -Value 30
+        }
+    }
+    ```
+
+    .EXAMPLE
+    ```ps
+    Describe "d1" {
+        It "i1" {
+            Mock Get-Command { }
+            Get-Command -CommandName abc
+            Should -Invoke Get-Command -Times 1 -Exactly
+        }
+    }
+    ```
+
+    .EXAMPLE
+    ```ps
+    Describe "d1" {
+        It "i1" {
+            Mock Get-Command { }
+            Get-Command -CommandName abc
+            Should -Invoke Get-Command -Times 1 -Exactly
+        }
+    }
+    ```
+
+    .EXAMPLE
+    $true | Should -BeFalse
+
+    .EXAMPLE
+    $a | Should -Be 10
+
+    .EXAMPLE
+    Should -Invoke Get-Command -Times 1 -Exactly
+
+    .EXAMPLE
+    $user | Should -NotBeNullOrEmpty -ErrorAction Stop
+
+    .EXAMPLE
+    $planets.Name | Should -Be $Expected
 #>
 
     [CmdletBinding()]
@@ -157,7 +220,7 @@ function Should {
             AddErrorCallback   = $addErrorCallback
         }
 
-        if (-not $entry) { return } 
+        if (-not $entry) { return }
 
         if ($inputArray.Count -eq 0) {
             Invoke-Assertion @assertionParams -ValueToTest $null