docs(WisherTools.Helpers): 📝 add comment-based help to utility functi…

…ons (#4)

CHANGELOG.md

@@ -5,6 +5,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Added detailed comment-based help to all public functions in the `WisherTools.Helpers` module. This provides better guidance and documentation for the following functions:
+  - `Get-BackupFilePath`
+  - `Get-DirectoryPath`
+  - `Get-FunctionScriptBlock`
+  - `Test-ComputerPing`
+  - `Test-DirectoryExists`
+
+## [v0.1.0] - 2024-09-07
+
 ### Changed
 
 - Removed Test Requierments to Test release

build.yaml

@@ -99,7 +99,7 @@ Pester:
   # - tests/Unit
   # - tests/Integration
   ExcludeTag:
-    - helpQuality
+  #  - helpQuality
     - FunctionalQuality
     - TestQuality
   Tag:

source/Public/Get-BackupFilePath.ps1

@@ -1,3 +1,27 @@
+<#
+.SYNOPSIS
+Generates a unique backup file path with a timestamp.
+
+.DESCRIPTION
+This function generates a unique backup file path by appending a timestamp to a user-defined or default file prefix. It is typically used to ensure that each backup file created has a unique name.
+
+.PARAMETER BackupDirectory
+The directory where the backup file will be saved. Defaults to "C:\LHStuff\UserProfileTools\RegProfBackup".
+
+.PARAMETER Prefix
+The prefix for the backup file name. Defaults to "ProfileListBackup".
+
+.EXAMPLE
+Get-BackupFilePath -BackupDirectory "C:\Backups" -Prefix "RegistryBackup"
+
+Generates a backup file path in "C:\Backups" with the prefix "RegistryBackup".
+
+.OUTPUTS
+System.String
+
+.NOTES
+#>
+
 function Get-BackupFilePath {
     param (
         [string]$BackupDirectory = "C:\LHStuff\UserProfileTools\RegProfBackup",

source/Public/Get-DirectoryPath.ps1

@@ -1,3 +1,30 @@
+<#
+.SYNOPSIS
+Converts a base path to either a local or UNC path format.
+
+.DESCRIPTION
+This function converts a base path to a local path if the target is on the local computer, or to a UNC format if the target is on a remote computer.
+
+.PARAMETER BasePath
+The base directory path that needs to be converted.
+
+.PARAMETER ComputerName
+The name of the computer where the directory is located.
+
+.PARAMETER IsLocal
+Boolean value indicating if the target is local. If true, the function returns the local path format; if false, it returns a UNC path.
+
+.EXAMPLE
+Get-DirectoryPath -BasePath "C:\Files" -ComputerName "RemotePC" -IsLocal $false
+
+Converts the local path "C:\Files" to a UNC path for the remote computer.
+
+.OUTPUTS
+System.String
+
+.NOTES
+#>
+
 function Get-DirectoryPath {
     [CmdletBinding()]
     param (

source/Public/Get-FunctionScriptBlock.ps1

@@ -1,3 +1,24 @@
+<#
+.SYNOPSIS
+Retrieves the script block of a specified PowerShell function.
+
+.DESCRIPTION
+This function dynamically retrieves the script block definition of a specified PowerShell function. It can be used to examine the contents of an existing function.
+
+.PARAMETER FunctionName
+The name of the function whose script block is to be retrieved.
+
+.EXAMPLE
+Get-FunctionScriptBlock -FunctionName 'Get-Process'
+
+Retrieves the script block of the 'Get-Process' function.
+
+.OUTPUTS
+System.String
+
+.NOTES
+#>
+
 function Get-FunctionScriptBlock {
     param (
         [string]$FunctionName

source/Public/Test-ComputerPing.ps1

@@ -1,3 +1,27 @@
+<#
+.SYNOPSIS
+Pings a computer to check if it is online.
+
+.DESCRIPTION
+This function sends a ping request to the specified computer and returns a boolean value indicating whether the computer is reachable. A configurable timeout can be specified for the ping.
+
+.PARAMETER ComputerName
+The name of the computer to be pinged.
+
+.PARAMETER Timeout
+The timeout value for the ping request in milliseconds. The default value is 2000 ms (2 seconds).
+
+.EXAMPLE
+Test-ComputerPing -ComputerName "RemotePC" -Timeout 3000
+
+Pings the computer "RemotePC" with a timeout of 3 seconds to check if it's online.
+
+.OUTPUTS
+System.Boolean
+
+.NOTES
+#>
+
 function Test-ComputerPing {
     [CmdletBinding()]
     param (

source/Public/Test-DirectoryExists.ps1

@@ -1,3 +1,24 @@
+<#
+.SYNOPSIS
+Ensures that a specified directory exists, and creates it if necessary.
+
+.DESCRIPTION
+This function checks whether a directory exists. If the directory does not exist, it creates the directory at the specified path.
+
+.PARAMETER Directory
+The path of the directory to check or create.
+
+.EXAMPLE
+Test-DirectoryExists -Directory "C:\Backups"
+
+Checks if the directory "C:\Backups" exists. If not, the function creates it.
+
+.OUTPUTS
+None
+
+.NOTES
+#>
+
 function Test-DirectoryExists {
     param (
         [string]$Directory