Update help files & add tests for help integrity (#401)

* ✅ Add tests for module help * 📝 Update documentation - Fix formatting issues in Markdown files - Update missing output type information - Add author information for commands - Tidying up files, adding related links, whitespace adjustments. * 📝 Update OutputType attribute for Get-Karma * 🎨 Update Show-Karma formatter to show correct param * 📝 Remove CBH from Get-Blank PS ignores external help for functions that still have CBH, so best to just remove the CBH for Get-Blank and move any extra info into the help file proper. * 🚀 Update build to put help files in `en` - Linux was failing since culture is en-US not en-us - Use `en` since that covers all English language cultures
vexx32 · Jul 10, 2020 · 430078e · 430078e
1 parent 0e0ac28
commit 430078e
Show file tree

Hide file tree

Showing 22 changed files with 566 additions and 222 deletions.
diff --git a/.gitignore b/.gitignore
@@ -3,3 +3,5 @@
 *.temppoint.*
 *.format.ps1xml
 PSKoans.psproj
+
+PSKoans/*/PSKoans-help.xml
diff --git a/Build/Build-Module.ps1 b/Build/Build-Module.ps1
@@ -34,7 +34,7 @@ catch {
 }
 
 # Build external help files from Platyps MD files
-New-ExternalHelp -Path "$env:PROJECTROOT/docs/" -OutputPath "$env:PROJECTROOT/PSKoans/en-us"
+New-ExternalHelp -Path "$env:PROJECTROOT/docs/" -OutputPath "$env:PROJECTROOT/PSKoans/en"
 
 Copy-Item -Path "$env:PROJECTROOT/PSKoans" -Destination $env:BUILTMODULEPATH -Recurse -PassThru |
     Where-Object { -not $_.PSIsContainer }
diff --git a/Deploy/Publish.ps1 b/Deploy/Publish.ps1
@@ -27,7 +27,7 @@ if ($OutputDirectory) {
 
 $HelpFile = Get-ChildItem -Path "$PSScriptRoot/PSKoans" -File -Recurse -Filter '*-help.xml'
 
-if ($HelpFile.Directory -notmatch 'en-us|\w{1,2}-\w{1,2}') {
+if ($HelpFile.Directory -notmatch 'en|\w{1,2}(-\w{1,2})?') {
     $PSCmdlet.WriteError(
         [System.Management.Automation.ErrorRecord]::new(
             [IO.FileNotFoundException]::new("Help files are missing!"),

diff --git a/PSKoans/Public/Get-Blank.ps1 b/PSKoans/Public/Get-Blank.ps1
@@ -1,43 +1,12 @@
 function Get-Blank {
-    <#
-        .SYNOPSIS
-        Get-Blank returns a blank object that represents no value, and is considered equal to
-        no other object or value.
-
-        .DESCRIPTION
-        Get-Blank returns an object of type [Blank] as defined in the PSKoans module.
-        This object is not equivalent to any other type of object, including itself, when compared
-        with a standard `-eq` comparison.
-
-        The only exception, which is unavoidable, is that it is considered equal to $true when
-        $true is on the left-hand side of the comparison. Tthis kind of comparison may sometimes
-        need to be carefully avoided when framing a koan assertion.
-
-        For instance, the following assertion WILL pass, although it should not:
-
-            ____ | Should -BeTrue
-
-        .EXAMPLE
-        __ | Should -Be (4 + 1)
-
-        .EXAMPLE
-        $Date = Get-Date
-        $____ | Should -Be $Date
-
-        .EXAMPLE
-        $Num = Get-Random
-        ____ | Should -Not -Be $num
-    #>
     [CmdletBinding(HelpUri = 'https://github.com/vexx32/PSKoans/tree/main/docs/Get-Blank.md')]
     [OutputType('Blank')]
     [Alias('__', '____', 'FILL_ME_IN')]
     param(
-        # Used to capture the input in a pipeline context, to avoid erroring out in those contexts.
         [Parameter(ValueFromPipeline, DontShow)]
         [object]
         ${|PipeInput},
 
-        # Used to capture parameter names and arguments when used as a substitute for any other cmdlet.
         [Parameter(ValueFromRemainingArguments, DontShow)]
         [object[]]
         ${|ParameterInput}

diff --git a/PSKoans/Public/Get-Karma.ps1 b/PSKoans/Public/Get-Karma.ps1
@@ -1,7 +1,7 @@
 function Get-Karma {
     [CmdletBinding(DefaultParameterSetName = 'Default',
         HelpUri = 'https://github.com/vexx32/PSKoans/tree/main/docs/Get-Karma.md')]
-    [OutputType([void])]
+    [OutputType('PSKoans.Result, PSKoans.CompleteResult')]
     [Alias()]
     param(
         [Alias('Koan', 'File')]

diff --git a/PSKoans/Public/Get-PSKoanSetting.ps1 b/PSKoans/Public/Get-PSKoanSetting.ps1
@@ -1,6 +1,6 @@
 function Get-PSKoanSetting {
     [CmdletBinding(HelpUri = 'https://github.com/vexx32/PSKoans/tree/main/docs/Get-PSKoanSetting.md')]
-    [OutputType([object], [PSCustomObject])]
+    [OutputType([string], [PSCustomObject])]
     param(
         [Parameter()]
         [string]

diff --git a/Tests/ModuleHelp.Tests.ps1 b/Tests/ModuleHelp.Tests.ps1
@@ -0,0 +1,88 @@
+#region Discovery
+
+$ModuleName = 'PSKoans'
+
+#endregion Discovery
+
+BeforeAll {
+    $ModuleName = 'PSKoans'
+    Import-Module $ModuleName
+}
+
+Describe "$ModuleName Sanity Tests - Help Content" -Tags 'Module' {
+
+    #region Discovery
+
+    # The module will need to be imported during Discovery since we're using it to generate test cases / Context blocks
+    Import-Module $ModuleName
+
+    $ShouldProcessParameters = 'WhatIf', 'Confirm'
+
+    # Generate command list for generating Context / TestCases
+    $Module = Get-Module $ModuleName
+    $CommandList = @(
+        $Module.ExportedFunctions.Keys
+        $Module.ExportedCmdlets.Keys
+    )
+
+    #endregion Discovery
+
+    foreach ($Command in $CommandList) {
+        Context "$Command - Help Content" {
+
+            #region Discovery
+
+            $Help = @{ Help = Get-Help -Name $Command -Full | Select-Object -Property * }
+            $Parameters = Get-Help -Name $Command -Parameter * -ErrorAction Ignore |
+                Where-Object { $_.Name -and $_.Name -notin $ShouldProcessParameters } |
+                ForEach-Object {
+                    @{
+                        Name        = $_.name
+                        Description = $_.Description.Text
+                    }
+                }
+            $Ast = @{
+                # Ast will be $null if the command is a compiled cmdlet
+                Ast        = (Get-Content -Path "function:/$Command" -ErrorAction Ignore).Ast
+                Parameters = $Parameters
+            }
+            $Examples = $Help.Help.Examples.Example | ForEach-Object { @{ Example = $_ } }
+
+            #endregion Discovery
+
+            It "has help content for $Command" -TestCases $Help {
+                $Help | Should -Not -BeNullOrEmpty
+            }
+
+            It "contains a synopsis for $Command" -TestCases $Help {
+                $Help.Synopsis | Should -Not -BeNullOrEmpty
+            }
+
+            It "contains a description for $Command" -TestCases $Help {
+                $Help.Description | Should -Not -BeNullOrEmpty
+            }
+
+            It "lists the function author in the Notes section for $Command" -TestCases $Help {
+                $Notes = $Help.AlertSet.Alert.Text -split '\n'
+                $Notes[0].Trim() | Should -BeLike "Author: *"
+            }
+
+            # This will be skipped for compiled commands ($Ast.Ast will be $null)
+            It "has a help entry for all parameters of $Command" -TestCases $Ast -Skip:(-not ($Parameters -and $Ast.Ast)) {
+                @($Parameters).Count | Should -Be $Ast.Body.ParamBlock.Parameters.Count -Because 'the number of parameters in the help should match the number in the function script'
+            }
+
+            It "has a description for $Command parameter -<Name>" -TestCases $Parameters -Skip:(-not $Parameters) {
+                $Description | Should -Not -BeNullOrEmpty -Because "parameter $Name should have a description"
+            }
+
+            It "has at least one usage example for $Command" -TestCases $Help {
+                $Help.Examples.Example.Code.Count | Should -BeGreaterOrEqual 1
+            }
+
+            It "lists a description for $Command example: <Title>" -TestCases $Examples {
+                $Example.Remarks | Should -Not -BeNullOrEmpty -Because "example $($Example.Title) should have a description!"
+            }
+        }
+    }
+}
diff --git a/docs/Get-Blank.md b/docs/Get-Blank.md
@@ -8,28 +8,40 @@ schema: 2.0.0
 # Get-Blank
 
 ## SYNOPSIS
+
 Gets a blank item that does not equal anything.
 
 ## SYNTAX
 
-```
+```powershell
 Get-Blank [[-|PipeInput] <Object>] [[-|ParameterInput] <Object[]>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
-Gets a blank object that is never equal to anything, including itself.
-This function exists to permit blank spaces such as `__` to be used without quotation marks where it is situationally appropriate.
+
+Get-Blank returns an object of type [Blank] as defined in the PSKoans module.
+This object is not equivalent to any other type of object, including itself, when compared
+with a standard `-eq` comparison.
+
+The only exception, which is unavoidable, is that it is considered equal to $true when
+$true is on the left-hand side of the comparison. This kind of comparison may sometimes
+need to be carefully avoided when framing a koan assertion.
+
+For instance,an assertion such as `____ | Should -BeTrue` WILL pass, although it should not.
 
 ## EXAMPLES
 
 ### EXAMPLE 1
+
 ```powershell
+
 Get-Blank
 ```
 
 Returns a blank object.
 
 ### EXAMPLE 2
+
 ```powershell
 __
 ```
@@ -38,48 +50,56 @@ Returns a blank object.
 
 ## PARAMETERS
 
-### -|ParameterInput
-Used to capture parameter names and arguments when used as a substitute for any other cmdlet.
-This parameter is not intended to be used directly, and collects all argument names and values.
+### -|PipeInput
+
+Used to capture the input in a pipeline context, to avoid erroring out in those contexts.
+This parameter is not intended to be used directly, and captures all pipeline input.
 
 ```yaml
-Type: Object[]
+Type: Object
 Parameter Sets: (All)
 Aliases:
 
 Required: False
-Position: 2
+Position: 1
 Default value: None
-Accept pipeline input: False
+Accept pipeline input: True (ByValue)
 Accept wildcard characters: False
 ```
 
-### -|PipeInput
-Used to capture the input in a pipeline context, to avoid erroring out in those contexts.
-This parameter is not intended to be used directly, and captures all pipeline input.
+### -|ParameterInput
+
+Used to capture parameter names and arguments when used as a substitute for any other cmdlet.
+This parameter is not intended to be used directly, and collects all argument names and values.
 
 ```yaml
-Type: Object
+Type: Object[]
 Parameter Sets: (All)
 Aliases:
 
 Required: False
-Position: 1
+Position: 2
 Default value: None
-Accept pipeline input: True (ByValue)
+Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
 ### CommonParameters
+
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
 
 ## INPUTS
 
 ## OUTPUTS
 
 ### Blank
+
+An object that has no value, and is generally considered to be not equal to any value, including null.
+
 ## NOTES
 
+Author: Joel Sallow (@vexx32)
+
 ## RELATED LINKS
 
-[https://github.com/vexx32/PSKoans](https://github.com/vexx32/PSKoans)
+[PSKoans](https://github.com/vexx32/PSKoans/tree/main/docs/PSKoans.md)