Fix should help examples

BUILD.md

@@ -1,13 +1,48 @@
-## Building Pester
+# Building Pester
+
+Pester is written in Powershell and C#.  The Microsoft .NET 4.5.2 Framework is required to build the Pester binaries.
 
 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`.
 
-### Required Software
+## Required Software
 
-#### Install .NET Core 3.1 SDK
+### 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
+
+TODO document parameters, tests executed in pipelines.
+
+```powershell
+.\test.ps1 -CI -SkipPTests -NoBuild -File ${filename}
+```
+
+## Continuous Integration
+
+The Azure Devops Pipeline azure-pipelines.yml file contains the code used for builds, unit and integration tests.
+
+## Documentation
+
+Documentation is available in the repo, the 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,76 @@ 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
     about_Pester
+
+    .EXAMPLE
+    Describe "d1" {
+        BeforeEach { $be = 1 }
+        It "i1" {
+            $be = 2
+        }
+        AfterEach { Write-Host "AfterEach: $be" }
+    }
+
+    .EXAMPLE
+    Describe "d1" {
+        It "i1" {
+            $user = Get-User
+            $user | Should -NotBeNullOrEmpty -ErrorAction Stop
+            $user |
+                Should -HaveProperty Name -Value "Jakub" |
+                Should -HaveProperty Age  -Value 30
+        }
+    }
+
+    .EXAMPLE
+    Describe "d1" {
+        It "i1" {
+            Mock Get-Command { }
+            Get-Command -CommandName abc
+            Should -Invoke Get-Command -Times 1 -Exactly
+        }
+    }
+
+    .EXAMPLE
+    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 +210,7 @@ function Should {
             AddErrorCallback   = $addErrorCallback
         }
 
-        if (-not $entry) { return } 
+        if (-not $entry) { return }
 
         if ($inputArray.Count -eq 0) {
             Invoke-Assertion @assertionParams -ValueToTest $null