I've started writing built-in help text for my PowerShell scripts (at least the ones customers have to use), and spent a lot of time trying to figure out why it would not show my custom text. I figured it out and am not sure if this is a bug or a feature.
The thoughtful can embed specially-formatted help text within a PowerShell script to document the program's purpose, how to use it, examples, etc., and this is available via the Get-Help mechanism. Get-Help essentially reads your script, extracts the help info, and merges it with what PowerShell would produce by default.
This is best illustrated by example, where the embedded help is in red:
# This program does some really important stuff.
# We're not sure why, but it just does.
<#
.SYNOPSIS
Do some important stuff, and sometimes even very important stuff
.PARAMETER Very
Do even MORE stuff
#>
Param(
[Parameter(Mandatory = $False)]
[switch] $Very
)
if ($Very)
{
Write-Output "Not just important, but *very* important"
}
else
{
Write-Output "Merely important"
}
Powershell uses the # characters to comment to the end of line, but also supports using <# and #> to surround a large block; this is akin to /*...*/ in C.
This commented text contains the special format notations that allow me to denote different sections of my extra help, in this case a .SYNOPSIS and .PARAMETER to document a command-line parameter. There are at least a dozen other documentation markers available.
Once we've written our documentation, we can check it out by asking PowerShell to show us help for our new command while including our additions, but—alas—we see only:
PS> Get-Help MyTest -Full MyTest.ps1 [-Very] [<CommonParameters>]
This is the stock help information you'd get from any script: it's able to parse it to pull out the actual Param(...) information from the script body (not just the comments), but that's about as far as it goes. It's definitely not finding my custom help info.
Turns out this this had nothing to do with the path, the lack of .\ in front of the filename (or any other pathing), the failure to use the .ps1 extension, or upper/lower casing of the name. Instead it was the lack of a blank line prior to the opening <# comment opener:
# This help text isn't seen <# .SYNOPSIS |
# This help text is
note blank line here
<#
.SYNOPSIS
|
Having done this, we see the full (if not important) help text:
PS> get-help mytest -full
NAME
C:\SomePath\MyTest.ps1
SYNOPSIS
Do some important stuff, and sometimes even very important stuff
SYNTAX
C:\SomePath\MyTest.ps1 [-Very] [<CommonParameters>]
DESCRIPTION
PARAMETERS
-Very [<SwitchParameter>]
Do even MORE stuff
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
RELATED LINKS
I don't know if this is a bug or a documented thing, but it certainly wasn't obvious to me, and I spent a fair amount of time on it.
Comments