description | ms.date | title |
---|---|---|
PowerShell provides a mechanism for programmers to document their scripts using special comment directives. The Get-Help cmdlet generates documentation from these directives. |
05/19/2021 |
Comment-Based Help |
PowerShell provides a mechanism for programmers to document their scripts using special comment directives. Comments using such syntax are called help comments. The cmdlet Get-Help generates documentation from these directives.
A help comment contains a help directive of the form .name followed on one or more subsequent lines by the help content text. The help comment can be made up of a series of single-line-comments or a delimited-comment (§2.2.3). The set of comments comprising the documentation for a single entity is called a help topic.
For example,
# <help-directive-1>
# <help-content-1>
...
# <help-directive-n>
# <help-content-n>
or
<#
<help-directive-1>
<help-content-1>
...
<help-directive-n>
<help-content-n>
#>
All of the lines in a help topic must be contiguous. If a help topic follows a comment that is not part of that topic, there must be at least one blank line between the two.
The directives can appear in any order, and some of the directives may appear multiple times.
Directive names are not case-sensitive.
When documenting a function, help topics may appear in one of three locations:
- Immediately before the function definition with no more than one blank line between the last line of the function help and the line containing the function statement.
- Inside the function's body immediately following the opening curly bracket.
- Inside the function's body immediately preceding the closing curly bracket.
When documenting a script file, help topics may appear in one of two locations:
- At the beginning of the script file, optionally preceded by comments and blank lines only. If the first item in the script after the help is a function definition, there must be at least two blank lines between the end of the script help and that function declaration. Otherwise, the help will be interpreted as applying to the function instead of the script file.
- At the end of the script file.
Syntax:
.DESCRIPTION
Description:
This directive allows for a detailed description of the function or script. (The .SYNOPSIS
directive (§A.2.11) is intended for a brief description.) This directive can be used only once
in each topic.
Examples:
<#
.DESCRIPTION
Computes Base to the power Exponent. Supports non-negative integer
powers only.
#>
Syntax:
.EXAMPLE
Description:
This directive allows an example of command usage to be shown.
If this directive occurs multiple times, each associated help content block is displayed as a separate example.
Examples:
<#
.EXAMPLE
Get-Power 3 4
81
.EXAMPLE
Get-Power -Base 3 -Exponent 4
81
#>
Syntax:
.EXTERNALHELP <XMLHelpFilePath>
Description:
This directive specifies the path to an XML-based help file for the script or function.
Although comment-based help is easier to implement, XML-based Help is required if more precise control is needed over help content or if help topics are to be translated into multiple languages. The details of XML-based help are not defined by this specification.
Examples:
<#
.ExternalHelp C:\MyScripts\Update-Month-Help.xml
#>
Syntax:
.FORWARDHELPCATEGORY <Category>
Description:
Specifies the help category of the item in ForwardHelpTargetName (§A.2.5). Valid values are Alias, All, Cmdlet, ExternalScript, FAQ, Filter, Function, General, Glossary, HelpFile, Provider, and ScriptCommand. Use this directive to avoid conflicts when there are commands with the same name.
Examples:
See §A.2.5.
Syntax:
.FORWARDHELPTARGETNAME <Command-Name>
Description:
Redirects to the help topic specified by <Command-Name>
.
Examples:
function Help {
<#
.FORWARDHELPTARGETNAME Get-Help
.FORWARDHELPCATEGORY Cmdlet
#>
...
}
The command Get-Help help
is treated as if it were Get-Help Get-Help
instead.
Syntax:
.INPUTS
Description:
The pipeline can be used to pipe one or more objects to a script or function. This directive is used to describe such objects and their types.
If this directive occurs multiple times, each associated help content block is collected in the one documentation entry, in the directives' lexical order.
Examples:
<#
.INPUTS
None. You cannot pipe objects to Get-Power.
.INPUTS
For the Value parameter, one or more objects of any kind can be written
to the pipeline. However, the object is converted to a string before it
is added to the item.
#>
function Process-Thing {
param ( ...
[Parameter(ValueFromPipeline=$true)]
[object[]]$Value,
...
)
...
}
Syntax:
.LINK
Description:
This directive specifies the name of a related topic.
If this directive occurs multiple times, each associated help content block is collected in the one documentation entry, in the directives' lexical order.
The Link directive content can also include a URI to an online version of the same help topic. The online version is opens when Get-Help is invoked with the Online parameter. The URI must begin with "http" or "https".
Examples:
<#
.LINK
Online version: http://www.acmecorp.com/widget.html
.LINK
Set-ProcedureName
#>
Syntax:
.NOTES
Description:
This directive allows additional information about the function or script to be provided. This directive can be used only once in each topic.
Examples:
<#
.Notes
*arbitrary text goes here*
#>
Syntax:
.OUTPUTS
Description:
This directive is used to describe the objects output by a command.
If this directive occurs multiple times, each associated help content block is collected in the one documentation entry, in the directives' lexical order.
Examples:
<#
.OUTPUTS
double - Get-Power returns Base to the power Exponent.
.OUTPUTS
None unless the -PassThru switch parameter is used.
#>
Syntax:
.PARAMETER <Parameter-Name>
Description:
This directive allows for a detailed description of the given parameter. This directive can be used once for each parameter. Parameter directives can appear in any order in the comment block; however, the order in which their corresponding parameters are actually defined in the source determines the order in which the parameters and their descriptions appear in the resulting documentation.
An alternate format involves placing a parameter description comment immediately before the declaration of the corresponding parameter variable's name. If the source contains both a parameter description comment and a Parameter directive, the description associated with the Parameter directive is used.
Examples:
<#
.PARAMETER Base
The integer value to be raised to the Exponent-th power.
.PARAMETER Exponent
The integer exponent to which Base is to be raised.
#>
function Get-Power {
param ([long]$Base, [int]$Exponent)
...
}
function Get-Power {
param ([long]
# The integer value to be raised to the Exponent-th power.
$Base,
[int]
# The integer exponent to which Base is to be raised.
$Exponent
)
...
}
Syntax:
.SYNOPSIS
Description:
This directive allows for a brief description of the function or script. (The .DESCRIPTION
directive (§A.2.1) is intended for a detailed description.) This directive can be used only once
in each topic.
Examples:
<#
.SYNOPSIS
Computes Base to the power Exponent.
#>