基于评论的帮助

PowerShell 为程序员提供了一种使用特殊注释指令记录脚本的机制。使用这种语法的注释称为帮助注释。 cmdlet Get-Help 从这些指令生成文档。

A.1 简介

帮助注释包含 .name 形式的帮助指令，后面的一行或多行是帮助内容文本。帮助注释可以由一系列单行注释或分隔注释组成（第2.2.3节）。组成单个实体的文档的注释集称为帮助主题。

例如，

# <help-directive-1>
# <help-content-1>
...

# <help-directive-n>
# <help-content-n>

或者

<#
<help-directive-1>
<help-content-1>
...

<help-directive-n>
<help-content-n>
#>

帮助主题中的所有行都必须是连续的。如果帮助主题后面的注释不属于该主题，则两者之间必须至少有一个空行。

这些指令可以按任何顺序出现，并且某些指令可能会出现多次。

指令名称不区分大小写。

记录函数时，帮助主题可能会出现在以下三个位置之一：

• 紧邻函数定义之前，函数帮助的最后一行与包含函数语句的行之间不超过一个空行。
• 在函数体内紧跟在左大括号之后。
• 在函数体内紧邻右花括号之前。

记录脚本文件时，帮助主题可能会出现在以下两个位置之一：

• 在脚本文件的开头，前面可以选择仅添加注释和空行。如果脚本中帮助之后的第一项是函数定义，则脚本帮助末尾和该函数声明之间必须至少有两个空行。否则，帮助将被解释为应用于函数而不是脚本文件。
• 在脚本文件的末尾。

A.2 帮助指令

A.2.1.描述

语法：

.DESCRIPTION

描述：

该指令允许对函数或脚本进行详细描述。 （.SYNOPSIS 指令 (§A.2.11) 用于简要描述。）该指令在每个主题中只能使用一次。

示例：

<#
.DESCRIPTION
Computes Base to the power Exponent. Supports non-negative integer
powers only.
#>

A.2.2.示例

语法：

.EXAMPLE

描述：

该指令允许显示命令用法的示例。

如果此指令多次出现，则每个关联的帮助内容块将显示为单独的示例。

示例：

<#
.EXAMPLE
Get-Power 3 4
81

.EXAMPLE
Get-Power -Base 3 -Exponent 4
81
#>

A.2.3.外部帮助

语法：

.EXTERNALHELP <XMLHelpFilePath>

描述：

该伪指令指定脚本或函数的基于 XML 的帮助文件的路径。

虽然基于注释的帮助更容易实现，但如果需要对帮助内容进行更精确的控制或者需要将帮助主题翻译成多种语言，则需要基于 XML 的帮助。本规范未定义基于 XML 的帮助的详细信息。

示例：

<#
.ExternalHelp C:\MyScripts\Update-Month-Help.xml
#>

A.2.4.转发帮助类别

语法：

.FORWARDHELPCATEGORY <Category>

描述：

指定 ForwardHelpTargetName 中项目的帮助类别 (§A.2.5)。有效值为别名、全部、Cmdlet、ExternalScript、FAQ、 >过滤器、函数、常规、词汇表、帮助文件、提供程序 > 和脚本命令。使用此指令可以避免存在同名命令时发生冲突。

示例：

参见§A.2.5。

A.2.5 .FORWARDHELPTARGETNAME

语法：

.FORWARDHELPTARGETNAME <Command-Name>

描述：

重定向到 <Command-Name> 指定的帮助主题。

示例：

function Help {
<#
.FORWARDHELPTARGETNAME Get-Help
.FORWARDHELPCATEGORY Cmdlet
#>
    ...
}

命令 Get-Help help 被视为 Get-Help Get-Help。

A.2.6.输入

语法：

.INPUTS

描述：

管道可用于将一个或多个对象通过管道传输到脚本或函数。该指令用于描述此类对象及其类型。

如果此指令多次出现，则每个关联的帮助内容块都会按照指令的词汇顺序收集在一个文档条目中。

示例：

<#
.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,
        ...
    )
    ...
}

A.2.7 .LINK

语法：

.LINK

描述：

该指令指定相关主题的名称。

如果此指令多次出现，则每个关联的帮助内容块都会按照指令的词汇顺序收集在一个文档条目中。

Link 指令内容还可以包括同一帮助主题的在线版本的 URI。当使用 Online 参数调用 Get-Help 时，将打开在线版本。 URI 必须以“http”或“https”开头。

示例：

<#
.LINK
Online version: http://www.acmecorp.com/widget.html

.LINK
Set-ProcedureName
#>

A.2.8.注释

语法：

.NOTES

描述：

该指令允许提供有关函数或脚本的附加信息。该指令在每个主题中只能使用一次。

示例：

<#
.Notes
*arbitrary text goes here*
#>

A.2.9.输出

语法：

.OUTPUTS

描述：

该伪指令用于描述命令输出的对象。

如果此指令多次出现，则每个关联的帮助内容块都会按照指令的词汇顺序收集在一个文档条目中。

示例：

<#
.OUTPUTS
double - Get-Power returns Base to the power Exponent.

.OUTPUTS
None unless the -PassThru switch parameter is used.
#>

A.2.10.参数

语法：

.PARAMETER <Parameter-Name>

描述：

该指令允许对给定参数进行详细描述。该指令可以对每个参数使用一次。参数指令可以以任意顺序出现在注释块中；然而，它们对应的参数在源中实际定义的顺序决定了参数及其描述在结果文档中出现的顺序。

另一种格式涉及在相应参数变量名称的声明之前放置参数描述注释。如果源同时包含参数描述注释和参数指令，则使用与参数指令关联的描述。

示例：

<#
.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
    )
    ...
}

A.2.11.概要

语法：

.SYNOPSIS

描述：

该指令允许对函数或脚本进行简短描述。 （.DESCRIPTION 指令 (§A.2.1) 用于详细描述。）该指令在每个主题中只能使用一次。

示例：

<#
.SYNOPSIS
Computes Base to the power Exponent.
#>