Private/New-PstCommentBasedHelp.ps1
|
function New-PstCommentBasedHelp { <# .SYNOPSIS Generates comment-based help for PowerShell functions. .DESCRIPTION Creates formatted comment-based help text based on complexity level, function name, description, and parameters. .PARAMETER FunctionName The name of the function. .PARAMETER Description Brief description of what the function does. .PARAMETER Parameters Array of parameter hashtables (normalized format). .PARAMETER Complexity The complexity level: Basic, Standard, or Advanced. .PARAMETER Examples Optional array of example strings to include. .EXAMPLE New-PstCommentBasedHelp -FunctionName "Get-UserData" -Description "Retrieves user data" -Complexity Basic Generates basic comment-based help. .NOTES Version: 1.0 Author: numidia Creation Date: 2025-12-01 Purpose: Generate comment-based help for functions #> [CmdletBinding()] [OutputType([string])] param( [Parameter(Mandatory = $true)] [string]$FunctionName, [Parameter(Mandatory = $false)] [string]$Description = "Description of $FunctionName", [Parameter(Mandatory = $false)] [hashtable[]]$Parameters = @(), [Parameter(Mandatory = $true)] [ValidateSet('Basic', 'Standard', 'Advanced')] [string]$Complexity, [Parameter(Mandatory = $false)] [string[]]$Examples = @() ) begin { Write-Debug "Begin '$($MyInvocation.MyCommand.Name)' at '$(Get-Date)'" } process { try { $features = Get-PstComplexityFeatures -Complexity $Complexity -Type Function $sb = [System.Text.StringBuilder]::new() # Start comment block [void]$sb.AppendLine(" <#") [void]$sb.AppendLine(" .SYNOPSIS") [void]$sb.AppendLine(" $Description") # Add DESCRIPTION if in schema if ($features.CommentHelp.Sections -contains 'Description') { [void]$sb.AppendLine() [void]$sb.AppendLine(" .DESCRIPTION") [void]$sb.AppendLine(" $Description") [void]$sb.AppendLine() [void]$sb.AppendLine(" Complexity Level: $Complexity") } # Add PARAMETER sections if ($Parameters.Count -gt 0 -and $features.CommentHelp.Sections -contains 'Parameter') { foreach ($param in $Parameters) { [void]$sb.AppendLine() [void]$sb.AppendLine(" .PARAMETER $($param.Name)") $paramDesc = if ($param.HelpMessage) { $param.HelpMessage } else { "The $($param.Name) parameter." } [void]$sb.AppendLine(" $paramDesc") } } # Add EXAMPLE sections $exampleCount = $features.CommentHelp.ExampleCount if ($features.CommentHelp.Sections -contains 'Example') { if ($Examples.Count -gt 0) { # Use provided examples for ($i = 0; $i -lt [Math]::Min($Examples.Count, $exampleCount); $i++) { [void]$sb.AppendLine() [void]$sb.AppendLine(" .EXAMPLE") [void]$sb.AppendLine(" $($Examples[$i])") } } else { # Generate default examples for ($i = 1; $i -le $exampleCount; $i++) { [void]$sb.AppendLine() [void]$sb.AppendLine(" .EXAMPLE") if ($Parameters.Count -gt 0) { $exampleParams = ($Parameters | Select-Object -First 2 | ForEach-Object { "-$($_.Name) `"value$i`"" }) -join ' ' [void]$sb.AppendLine(" $FunctionName $exampleParams") } else { [void]$sb.AppendLine(" $FunctionName") } [void]$sb.AppendLine(" Example $i description.") } } } # Add NOTES if in schema if ($features.CommentHelp.IncludeNotes) { [void]$sb.AppendLine() [void]$sb.AppendLine(" .NOTES") [void]$sb.AppendLine(" Version: 1.0") [void]$sb.AppendLine(" Author: numidia") [void]$sb.AppendLine(" Creation Date: $(Get-Date -Format 'yyyy-MM-dd')") [void]$sb.AppendLine(" Purpose: $Description") } # Add INPUTS/OUTPUTS for Advanced if ($Complexity -eq 'Advanced') { [void]$sb.AppendLine() [void]$sb.AppendLine(" .INPUTS") [void]$sb.AppendLine(" None. You cannot pipe objects to $FunctionName.") [void]$sb.AppendLine() [void]$sb.AppendLine(" .OUTPUTS") [void]$sb.AppendLine(" System.Object") } # Add LINK if in schema if ($features.CommentHelp.IncludeLinks) { [void]$sb.AppendLine() [void]$sb.AppendLine(" .LINK") [void]$sb.AppendLine(" https://github.com/NumidiaLive/MyPowershellTemplates") } # Close comment block [void]$sb.Append(" #>") Write-Verbose "Generated $Complexity comment-based help for '$FunctionName'" return $sb.ToString() } catch { Write-Error "Failed to generate comment-based help: $($_.Exception.Message)" $PSCmdlet.ThrowTerminatingError($_) } } end { Write-Debug "End '$($MyInvocation.MyCommand.Name)' at '$(Get-Date)'" } } |