Troubleshooting Comment-Based Help

• PowerShell Studio
• Tips and Tricks
• PowerShell HelpWriter

User Rating: 5 / 5

A Windows PowerShell user group member recently came to me with a question about comment-based help in Windows PowerShell. It reminded me again that comment-based help is not as easy to use as you might think. Here are a few tips to help you avoid and fix obvious pitfalls.

TIP: When testing help, be sure to restart your session between each test. Windows PowerShell caches help for the session, so changes to the help are effective only in a new session.

RTFM: about_Comment_Based_Help

The best way to avoid errors is to read the about_Comment_Based_Help topic. It covers issues like the placement of comment-based help in functions, scripts, and script modules. It lists the keywords and provides some useful examples. Be sure to start there. This post is supplemental.

Use Only Valid Keywords

Comment-based help must include only valid keywords. If even one keyword is invalid, Get-Help ignores the entire comment-based help block and displays auto-generated help.

The keyword names are case-insensitive, but they must be spelled exactly as specified. The dot and the keyword name cannot be separated by even one space. None of the keywords are required* in comment-based help, but you can’t add or change keywords, even it you really want a new one (such as .FILENAME, which would be a really good idea). If you use .NOTE (instead of .NOTES) or .EXAMPLES (instead of .EXAMPLE), Get-Help doesn’t display any of it.

It’s very picky! If the format of a keyword is wrong, such as forgetting to place the parameter name on the same line as the .PARAMETER keyword, the entire comment-based help block is ignored.

.SYNOPSIS
.DESCRIPTION
.PARAMETER
.EXAMPLE
.INPUTS
.OUTPUTS
.NOTES
.LINK
.COMPONENT
.ROLE
.FUNCTIONALITY
.FORWARDHELPTARGETNAME
.FORWARDHELPCATEGORY
.REMOTEHELPRUNSPACE
.EXTERNALHELP

*.ExternalHelp is required for function with Help XML files, but it’s not required for the comment-based help display.

Also, for function help placed immediately before the function, you can have no more than one line blank line between the end the help block and the line on which the function is defined. If there are two blank lines, Get-Help associates the help with the script or module file, not the function.

This is valid function help.

<#
 .DESCRIPTION
 Nice function
#>
function Get-NiceFunction {}

This is valid function help.

<#
 .DESCRIPTION
 Nice function
 
#>
function Get-NiceFunction {}

This doesn’t work. Get-Help displays auto-generated help for the function. It associates the help comments with the script, not the function.

<#
 .DESCRIPTION
 Nice function
#>
 
 
function Get-NiceFunction {}

Distinguish HelpMessage from Parameter Comments and .PARAMETER

There are three ways to add a parameter description to function help. I’ve listed them below in precedence order.

Notice that Get-Help displays a parameter comment only when there is at least one valid comment-based help keyword for the command and it is not a .PARAMETER keyword for the same parameter. If the parameter comment is the only help for the command, it is ignored.

Also, the HelpMessage attribute is part of auto-generated help, not comment-based help.

• The .PARAMETER keyword takes precedence over other parameter description types. Get-Help displays it even when it is the only comment-based help keyword for the function.

<#
    .PARAMETER Name
     Enter a unique name for the widget.
#>

• A parameter comment appears in the Get-Help display when there is valid comment-based help, but no .PARAMETER keyword for that parameter.

Param
(
    [Parameter(Mandatory = $true)]
    [string]
    # Enter a unique name for the widget.
    $Name
)

• The HelpMessage attribute appears in the Get-Help -Full and -ShowWindow display only when there is no help of any type for the command.

Param
(
    [Parameter(Mandatory = $true, HelpMessage = "Enter a unique name for the widget.")]
    [string]
    $Name
)

According to the MSDN docs, the HelpMessage attribute of a parameter appears when Windows PowerShell prompts for a mandatory parameter value, but Get-Help doesn’t display it. Based on my tests of Windows PowerShell 2.0 – 5.0 preview, Get-Help does display the HelpMessage attribute value in auto-generated help.

The HelpMessage attribute appears when you type !? in response to a mandatory parameter prompt.

function Get-CBHelp
{
    param
    (
        [Parameter(Mandatory = $true, 
                   HelpMessage = "Enter a unique name for the widget.")]
        [String]
        $Name
    )
    $Name
}

PS C:\> . .\Test-CBHelp.ps1"
PS C:\> Get-CBHelp
cmdlet Get-CBHelp at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
Name: !?
Enter a unique name for the widget.

However, it also appears in auto-generated help with -Full or -ShowWindow when there is no help for the command. To make Get-Help ignore the comment-based help and display auto-generated help, I’ll just delete the first “S” from .SYNOPSIS.

<# .SYNOPSIS 
    Tests elements of comment-based help 
.DESCRIPTION 
    This function doesn't do anything. It was created only for testing. 
.PARAMETER Name 
    This is the parameter keyword. 
.EXAMPLE 
    PS C:\&gt; Get-CBHelp -Name Plebius
    Plebius
#>
function Get-CBHelp
{
    Param
    (
        [Parameter(Mandatory = $true, HelpMessage = "This is the HelpMessage attribute.")]
        # Here is the parameter comment.
        [string]
        $Name
    )
    $Name
}

PS C:\> . .\Test-CBHelp.ps1
PS C:\> Get-Help -Full Get-CBHelp

NAME
Get-CBHelp

SYNTAX
Get-CBHelp [-Name] <string>  [<CommonParameters>]

PARAMETERS
-Name <string>
This is the HelpMessage attribute.

Required?                    true
Position?                    0
Accept pipeline input?       false
Parameter set name           (All)
Aliases                      None
Dynamic?                     false

Use .ExternalHelp for Function Help XML Files

There are no required keywords in comment-based help. For example, if you have a comment-based help block that contains only a .INPUTS keyword and its value, Get-Help displays the Inputs section that you specify and fills in the rest from auto-generated help.

The only keyword that might be thought of as required is .EXTERNALHELP. This comment keyword must appear when help for a function is written in a Help XML file. Unlike the help XML files for other command types, help XML files for functions do not have standard names or locations. Thus, without .EXTERNALHELP, Get-Help does not know where to look for an Help XML file, regardless of its name and location.

The value of the .EXTERNALHELP keyword is the name of the help XML file without a path. Get-Help looks for a file with that name in a language-specific subdirectory of the module directory.

For example, because of the value of the .EXTERNALHELP keyword, Get-Help knows that it should look for a help topic for my Update-OneGet function in the UpdateOneGet.psm1-help.xml file in the en-US (or de-DE, etc) directory of its module directory, ($home\Documents\WindowsPowerShell\Modules\UpdateOneGet\en-US\UpdateOneGet.psm1-help.xml).

# .EXTERNALHELP UpdateOneGet.psm1-help.xml
function Update-OneGet
{
    Param
    ...
(

For more information about writing XML help files for functions, see Writing XML Help for Advanced Functions.

For more information about naming help files so Get-Help can find them, see Naming Help Files.

Precedence

Comment-based help takes precedence over XML help, so if you have both, Get-Help gets only the comment-based help. However, the .EXTERNALHELP comment keyword takes precedence over comment-based help. So, if you have both, Get-Help gets only XML help.

For example, given the following comment-based help content, Get-Help displays the XML help in MyModule.psm1-help.xml and ignores the .LINK.

<#
.EXTERNALHELP MyModule.psm1-help.xml
.LINK
http://www.sapien.com/blog
#>

Use great tools

I need to mention that great PowerShell tools help you to avoid these syntactic problems.

For example, in PowerShell Help Writer, you write help topics in an environment customized for authoring Windows PowerShell help. You don’t need to worry about syntax or any other implementation details. You select a module and PowerShell Help Writer generates starter help topics with the correct syntax. If you have existing help, including comment-based help, it converts it automatically. This is really the ultimate help authoring environment.

In PowerShell Studio, the Function Builder (Insert function/Edit function) lets you compose comment-based help for a function while you’re writing the function. It adds the correct syntax so you don’t have to think about it.

PowerShell Studio also generates comment-based help on demand.

And, when you’re editing comment-based help in PowerShell Studio, PrimalSense suggests and inserts keywords with the correct spelling and format.

Writing comment-based help seems a bit more complicated than it needs to be. But knowing the “gotchas” makes the task of writing valid comment-based help a bit easier.

[Thanks to Windows PowerShell MVP Aleksandar Nikolic for correcting the “!?” omission in the original article.]

June Blender is a technology evangelist at SAPIEN Technologies, Inc. You can reach her at This email address is being protected from spambots. You need JavaScript enabled to view it. or follow her on Twitter at @juneb_get_help.

• Prev
• Next