feat(PesterExplorer): ✨ add detailed comment-based help for functions

* Added comment-based help to several functions to improve documentation.
* Enhanced user experience for new contributors by providing clear usage examples.
* Updated `CHANGELOG.md` to reflect these additions.

Author: Gilbert Sanchez

.github/prompts/PowerShellPrompts.prompt.md

@@ -0,0 +1,29 @@
+---
+mode: 'ask'
+---
+This project uses PwshSpectreConsole and Pester to render a TUI for Pester
+results.The TUI allows users to navigate through Pester run results, viewing
+details of containers, blocks, and tests.
+
+All suggestions should try to stay with 80 characters or 120 max. Use splatting
+when possible. You can create new lines after `|` to make it more readable.
+
+# Examples
+You can use the following when you create `.EXAMPLE` text for the comment based
+help. All Object parameters will use the $run variable from the following code:
+
+```
+$run = Invoke-Pester -Path 'tests' -PassThru
+```
+
+# Example 1
+```powershell
+$run = Invoke-Pester -Path 'tests' -PassThru
+$run | Show-PesterResults
+```
+
+An explanation of the example should be provided in the `.EXAMPLE` section with
+an empty line between the example and the explanation.
+
+# PowerShell Functions
+All functions should have a `[CmdletBinding()]` attribute.

.markdownlint.json

@@ -0,0 +1,6 @@
+{
+    "MD013": false,
+    "MD024": {
+        "siblings_only": true
+    }
+}

CHANGELOG.md

@@ -7,18 +7,24 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
 
+### Added
+
+- Added comment based help on private functions to make it easier for new
+  contributors to grok.
+
 ### Changed
 
 - The `Show-PesterResult` List panel now the files using relative path from the
   current directory. It also added padding on the selected item as well as an
   additional icon to show the highlight.
+- Formatted all the functions to stay under 80 character line limit. This is a
+  preference. We will have a 120 hard limit (when possible).
 
 ### Fixed
 
 - Removed extra item from the stack that tracked which layer of the view you
   were in.
 
-
 ## [0.1.0] Initial Version
 
 ### Added

PesterExplorer/Private/Format-PesterObjectName.ps1

@@ -1,4 +1,27 @@
 function Format-PesterObjectName {
+    <#
+    .SYNOPSIS
+    Format the name of a Pester object for display.
+
+    .DESCRIPTION
+    This function formats the name of a Pester object for display in a way that is compatible with Spectre.Console.
+    It uses the object's name and result to determine the appropriate icon and color for display.
+    It returns a string that can be used in Spectre.Console output.
+
+    .PARAMETER Object
+    The Pester object to format. This should be a Pester Run or TestResult object.
+    It is mandatory and can be piped in.
+
+    .PARAMETER NoColor
+    A switch to disable color formatting in the output. If specified, the name will be returned without any color
+    or icon.
+
+    .EXAMPLE
+    $pesterResult.Containers[0].Blocks[0] | Format-PesterObjectName
+
+    This would format the name of the first block in the first container of a Pester result,
+    returning a string with the appropriate icon and color based on the result of the test.
+    #>
     [CmdletBinding()]
     [OutputType([string])]
     param (

PesterExplorer/Private/Format-PesterTreeHash.ps1

@@ -1,4 +1,45 @@
 function Format-PesterTreeHash {
+    <#
+    .SYNOPSIS
+    Format a Pester object into a hashtable for tree display.
+
+    .DESCRIPTION
+    This function takes a Pester object and formats it into a hashtable that can
+    be used to display a tree structure in a TUI (Text User Interface). It
+    handles different types of Pester objects such as Run, Container, Block, and
+    Test, recursively building a tree structure with children nodes.
+
+    .PARAMETER Object
+    The Pester object to format. This can be a Run, Container, Block, or Test
+    object. The function will traverse the object and its children, formatting
+    them into a hashtable structure.
+
+    .EXAMPLE
+    $run = Invoke-Pester -Path 'tests' -PassThru
+    $treeHash = Format-PesterTreeHash -Object $run
+
+    .NOTES
+    This returns a hashtable with the following structure:
+    @{
+        Value = "Pester Run" # or the name of the object
+        Children = @(
+            @{
+                Value = "Container Name"
+                Children = @(
+                    @{
+                        Value = "Block Name"
+                        Children = @(
+                            @{
+                                Value = "Test Name"
+                                Children = @()
+                            }
+                        )
+                    }
+                )
+            }
+        )
+    }
+    #>
     [CmdletBinding()]
     [OutputType([hashtable])]
     param (

PesterExplorer/Private/Get-LastKeyPressed.ps1

@@ -1,4 +1,30 @@
 function Get-LastKeyPressed {
+    <#
+    .SYNOPSIS
+    Get the last key pressed in the console.
+
+    .DESCRIPTION
+    This function checks if any key has been pressed in the console and returns
+    the last key pressed. It is useful for handling user input in a TUI (Text
+    User Interface) environment.
+
+    .EXAMPLE
+    $key = Get-LastKeyPressed
+    if ($key -eq "Enter") {
+        # Make the TUI do something
+    }
+
+    This example retrieves the last key pressed and checks if it was the Enter
+    key.
+
+    .NOTES
+    This function is meant to be used in a TUI context where you need to
+    handle user input. It reads the console key buffer and returns the last key
+    pressed without displaying it on the console.
+    #>
+    [CmdletBinding()]
+    [OutputType([ConsoleKeyInfo])]
+    param ()
     $lastKeyPressed = $null
     while ([Console]::KeyAvailable) {
         $lastKeyPressed = [Console]::ReadKey($true)

PesterExplorer/Private/Get-ListFromObject.ps1

@@ -1,4 +1,29 @@
 function Get-ListFromObject {
+    <#
+    .SYNOPSIS
+    Create a list from a Pester object for creating the items for the list.
+
+    .DESCRIPTION
+    This function takes a Pester object (Run, Container, Block, or List) and
+    formats it into an ordered dictionary that can be used to display a tree
+    structure in a TUI (Text User Interface). It handles different types of
+    Pester objects, extracting relevant information such as container names,
+    block names, and test names. The function returns an ordered dictionary
+    where the keys are formatted names and the values are the corresponding
+    Pester objects.
+
+    .PARAMETER Object
+    The Pester object to format. This can be a Run, Container, Block, or List
+    object. The function will traverse the object and its children, formatting
+    them into an ordered dictionary structure.
+
+    .EXAMPLE
+    $run = Invoke-Pester -Path 'tests' -PassThru
+    $list = Get-ListFromObject -Object $run
+
+    This example retrieves a Pester run object and formats it into an ordered
+    dictionary for tree display.
+    #>
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
     param (

PesterExplorer/Private/Get-ListPanel.ps1

@@ -1,4 +1,29 @@
 function Get-ListPanel {
+    <#
+    .SYNOPSIS
+    Create a list panel for displaying items in a TUI.
+
+    .DESCRIPTION
+    This function generates a list panel that displays items in a TUI (Text User
+    Interface) using Spectre.Console. It formats the items based on whether they
+    are selected or not, and handles special cases like parent directories.
+
+    .PARAMETER List
+    An array of strings to display in the list. Each item can be a file path,
+    a test name, or a special item like '..' for parent directories.
+
+    .PARAMETER SelectedItem
+    The item that is currently selected in the list. This will be highlighted
+    differently from unselected items.
+
+    .EXAMPLE
+    Get-ListPanel -List @('file1.txt', 'file2.txt', '..') -SelectedItem 'file1.txt'
+
+    This example creates a list panel with three items, highlighting 'file1.txt'
+    as the selected item.
+    .NOTES
+    This is meant to be called by the main TUI function: Show-PesterResult
+    #>
     [CmdletBinding()]
     param (
         [array]
@@ -17,9 +42,11 @@ function Get-ListPanel {
         if($name -eq '..') {
             # This is a parent item, so we show it as a folder
             if ($name -eq $SelectedItem) {
-                Write-SpectreHost ":up_arrow: [Turquoise2]$name[/]" -PassThru | Format-SpectrePadded -Padding 1
+                Write-SpectreHost ":up_arrow: [Turquoise2]$name[/]" -PassThru |
+                    Format-SpectrePadded -Padding 1
             } else {
-                Write-SpectreHost "$name" -PassThru | Format-SpectrePadded -Padding 0
+                Write-SpectreHost "$name" -PassThru |
+                    Format-SpectrePadded -Padding 0
             }
         }
         elseif(Test-Path $name){
@@ -28,18 +55,32 @@ function Get-ListPanel {
                 $name
             )
             if ($name -eq $SelectedItem) {
-                Format-SpectreTextPath -Path $relativePath | Format-SpectrePadded -Padding 1
+                Format-SpectreTextPath -Path $relativePath |
+                    Format-SpectrePadded -Padding 1
             } else {
-                Format-SpectreTextPath -Path $relativePath -PathStyle $unselectedStyle | Format-SpectrePadded -Padding 0
+                $formatSpectreTextPathSplat = @{
+                    Path = $relativePath
+                    PathStyle = $unselectedStyle
+                }
+                Format-SpectreTextPath @formatSpectreTextPathSplat |
+                    Format-SpectrePadded -Padding 0
             }
         }
         else {
             if ($name -eq $SelectedItem) {
-                Write-SpectreHost ":right_arrow: [Turquoise2]$name[/]" -PassThru | Format-SpectrePadded -Padding 1
+                $writeSpectreHostSplat = @{
+                    PassThru = $true
+                    Message = ":right_arrow: [Turquoise2]$name[/]"
+                }
+                Write-SpectreHost @writeSpectreHostSplat |
+                    Format-SpectrePadded -Padding 1
             } else {
-                Write-SpectreHost $name -PassThru | Format-SpectrePadded -Padding 0
+                Write-SpectreHost $name -PassThru |
+                    Format-SpectrePadded -Padding 0
             }
         }
     }
-    $results | Format-SpectreRows | Format-SpectrePanel -Header "[white]List[/]" -Expand
+    $results |
+        Format-SpectreRows |
+        Format-SpectrePanel -Header "[white]List[/]" -Expand
 }