about_Comment_Based_Help

Статья
01/09/2025

Краткое описание

Описывается, как писать справку на основе комментариев для функций и скриптов.

Подробное описание

Вы можете написать контент справки на основе комментариев для функций и сценариев с помощью специальных ключевых слов справки.

Командлет get-Help отображает справку на основе комментариев в том же формате, в котором отображается содержимое справки командлета, созданное из XML-файлов. Пользователи могут использовать все параметрыGet-Help, такие как "Подробные", "Полные", "Примеры" и "Интернет", для отображения содержимого справки на основе комментариев.

Вы также можете создавать файлы справки на основе XML для функций и скриптов. Чтобы разрешить Get-Help командлету найти XML-файл справки для функции или скрипта, используйте ключевое .EXTERNALHELP слово. Без этого ключевого слова Get-Help не может найти справочное содержимое, основанное на XML, для функций или скриптов.

В этом разделе объясняется, как написать содержимое справки для функций и скриптов. Сведения о том, как отобразить содержимое справки для функций и скриптов, см. Get-Help.

Командлеты Update-Help и Save-Help работают только в XML-файлах. Справка, поддающаяся обновлению, не поддерживает справочные материалы, основанные на комментариях.

Синтаксис справки на основе комментариев

Чтобы создать содержимое справки на основе комментариев, можно использовать любой стиль комментариев: однострочные примечания или блокировать комментарии.

Синтаксис справки на основе комментариев выглядит следующим образом:

# .<help keyword>
# <help content>

<#
    .<help keyword>
    <help content>
#>

Справка на основе комментариев написана в виде ряда комментариев. Вы можете ввести символ # комментария перед каждой строкой комментариев или использовать <##> символы для создания блока комментариев. Все строки в блоке комментариев интерпретируются как комментарии.

Все строки в разделе справки на основе комментариев должны быть смежными. Если раздел справки на основе комментариев следует за комментарием, который не является частью раздела справки, то между последней строкой комментариев, отличной от справки, и началом справки на основе комментариев должно быть по крайней мере одна пустая строка.

Ключевые слова определяют каждый раздел справки на основе комментариев. Каждое ключевое слово справки на основе комментариев предшествует точке .. Ключевые слова могут отображаться в любом порядке. Имена ключевых слов не учитывает регистр.

Например, ключевое .Description слово предшествует описанию функции или скрипта.

<#
.Description
Get-Function displays the name and syntax of all functions in the session.
#>

Блок комментариев должен содержать по крайней мере одно ключевое слово. Некоторые ключевые слова, например .EXAMPLE, могут отображаться несколько раз в одном блоке комментариев. Содержимое справки для каждого ключевого слова начинается в строке после ключевого слова и может охватывать несколько строк.

Синтаксис справки на основе комментариев в функциях

Справка на основе комментариев для функции может отображаться в одном из трех расположений:

В начале текста функции.
В конце текста функции.
Перед ключевым словом function . Между последней строкой справки функции и ключевым словом function не может быть более одной пустой строки.

Например:

function Get-Function {
    <#
        .<help keyword>
        <help content>
    #>

    # function logic
}

function Get-Function {
    # function logic

    <#
        .<help keyword>
        <help content>
    #>
}

<#
    .<help keyword>
    <help content>
#>
function Get-Function { }

Синтаксис справки на основе комментариев в скриптах

Справка на основе комментариев для скрипта может отображаться в одном из следующих двух расположений в скрипте.

В начале файла скрипта. Справка по скрипту может предшествовать только примечаниям и пустым строкам.

Если первый элемент в тексте скрипта (после справки) является объявлением функции, между концем справки скрипта и объявлением функции должно быть не менее двух пустых строк. В противном случае справка интерпретируется как справка для функции, а не справка по скрипту.
В конце файла сценария. Однако если скрипт подписан, поместите справку на основе комментариев в начале файла скрипта. Конец скрипта занят блоком подписи.

Например:

<#
.<help keyword>
<help content>
#>
function Get-Function { }

function Get-Function { }
<#
.<help keyword>
<help content>
#>

Ключевые слова справки на основе комментариев

Ниже приведены допустимые ключевые слова справки на основе комментариев. Эти ключевые слова могут отображаться в любом порядке в контекстной справке, и они не учитывают регистр. Ключевые слова перечислены в этой статье в том порядке, в который они обычно отображаются в разделе справки.

.SYNOPSIS

Краткое описание функции или скрипта. Это ключевое слово можно использовать только один раз в каждом разделе.

.DESCRIPTION

Подробное описание функции или скрипта. Это ключевое слово можно использовать только один раз в каждом разделе.

.PARAMETER

Описание параметра. Добавьте ключевое .PARAMETER слово для каждого параметра в синтаксисе функции или скрипта.

Введите имя параметра в той же строке, что и ключевое .PARAMETER слово. Введите описание параметра в строках, приведенных ниже ключевого .PARAMETER слова. Windows PowerShell интерпретирует весь текст между строкой .PARAMETER и следующим ключевым словом или концом блока комментариев в рамках описания параметра. Описание может включать разрывы абзаца.

.PARAMETER  <Parameter-Name>

Ключевые слова параметров могут отображаться в любом порядке в блоке комментариев, но синтаксис функции или скрипта определяет порядок отображения параметров (и их описания) в разделе справки. Чтобы изменить порядок, измените синтаксис.

Можно также указать описание параметра, разместив комментарий в синтаксисе функции или скрипта непосредственно перед именем переменной параметра. Для работы этого необходимо также иметь блок комментариев с по крайней мере одним ключевым словом.

Если используется как комментарий синтаксиса, так и .PARAMETER ключевое слово, используется описание, связанное с .PARAMETER ключевым словом, и синтаксический комментарий игнорируется.

<#
.SYNOPSIS
    Short description here
#>
function Verb-Noun {
    [CmdletBinding()]
    param (
        # This is the same as .Parameter
        [string]$Computername
    )
    # Verb the Noun on the computer
}

.EXAMPLE

Пример команды, которая использует функцию или скрипт, а также пример выходных данных и описание. Повторите это ключевое слово для каждого примера.

.INPUTS

Типы объектов .NET, которые можно передать в функцию или скрипт. Можно также включить описание входных объектов.

.OUTPUTS

Тип .NET объектов, возвращаемых командлетом. Можно также включить описание возвращаемых объектов.

.NOTES

Дополнительные сведения о функции или скрипте.

.LINK

Имя связанного раздела. Значение отображается в строке ниже ключевого слова ".LINK" и должно предшествовать символу # комментария или включенному в блок комментариев.

Повторите ключевое слово для каждого связанного .LINK раздела.

Это содержимое отображается в разделе "Связанные ссылки" раздела справки.

Содержимое .Link ключевого слова также может включать универсальный идентификатор ресурса (URI) в веб-версию той же справки. Откроется онлайн-версия при использовании . Универсальный код ресурса (URI) должен начинаться с "http" или "https".

.COMPONENT

Имя технологии или функции, которая использует функцию или скрипт или к которой она связана. Параметр использует это значение для фильтрации результатов поиска, возвращаемыхGet-Help.

.ROLE

Имя роли пользователя для раздела справки. Параметр использует это значение для фильтрации результатов поиска, возвращаемыхGet-Help.

.FUNCTIONALITY

Ключевые слова, описывающие предполагаемое использование функции. Параметр использует это значение для фильтрации результатов поиска, возвращаемыхGet-Help.

.FORWARDHELPTARGETNAME

Перенаправляется в раздел справки для указанной команды. Вы можете перенаправить пользователей в любой раздел справки, включая содержимое справки для функции, скрипта, командлета или провайдера.

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

Указывает категорию справки элемента в .ForwardHelpTargetName. Допустимые значения: Alias, Cmdlet, HelpFileFunctionProviderGeneralFAQGlossaryScriptCommandExternalScriptFilterили .All Используйте это ключевое слово, чтобы избежать конфликтов при наличии команд с тем же именем.

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE

Указывает сеанс, содержащий раздел справки. Введите переменную, содержащую объект PSSession . Это ключевое слово используется командлетом Export-PSSession для поиска содержимого справки для экспортированных команд.

# .REMOTEHELPRUNSPACE <PSSession-variable>

.EXTERNALHELP

Указывает XML-файл справки для скрипта или функции.

# .EXTERNALHELP <XML Help File>

Ключевое .EXTERNALHELP слово требуется, если функция или скрипт документируются в XML-файлах. Без этого ключевого слова Get-Help не сможет найти XML-файл справки для функции или скрипта.

Ключевое .EXTERNALHELP слово имеет приоритет над другими ключевыми словами справки на основе комментариев. Если .EXTERNALHELP присутствует, Get-Help не отображает справку на основе комментариев, даже если не удается найти раздел справки, соответствующий значению ключевого слова .EXTERNALHELP.

Если функция экспортируется модулем, задайте значение ключевого .EXTERNALHELP слова в имя файла без пути. Get-Help ищет указанное имя файла в подкаталоге для конкретного языка каталога модуля. Нет требований к имени XML-файла справки для функции, но рекомендуется использовать следующий формат:

<ScriptModule.psm1>-help.xml

Если функция не включена в модуль, добавьте путь к файлу справки, основанному на XML. Если значение содержит путь и путь содержит вложенные каталоги, зависящие от пользовательского интерфейса, Get-Help выполняет поиск подкаталогов рекурсивно для XML-файла с именем скрипта или функции в соответствии со стандартами языка, установленными для Windows, так же, как и в каталоге модулей.

Дополнительные сведения о формате файла справки на основе XML командлетов см. в статье "Как написать справку по командлетам".

Автогенерированное содержимое

Имя, синтаксис, список параметров, таблица атрибутов параметров, общие параметры и примечания автоматически создаются командлетом Get-Help .

Имя.

Раздел справки по имени функции взят из имени функции в синтаксисе функции. Имя раздела справки по скрипту берется из имени файла скрипта. Чтобы изменить имя или его заглавную букву, измените синтаксис функции или имя файла скрипта.

Синтаксис

Раздел синтаксиса раздела справки создается из синтаксиса функции или скрипта. Чтобы добавить подробные сведения в синтаксис раздела справки, например тип параметра .NET, добавьте сведения в синтаксис. Если тип параметра не указан, тип объекта вставляется в качестве значения по умолчанию.

Список параметров

Список параметров в разделе справки создается из синтаксиса функции или скрипта и из описаний, добавляемых с помощью ключевого .Parameter слова. Параметры функции отображаются в разделе "Параметры " раздела справки в том же порядке, что они отображаются в синтаксисе функции или скрипта. Написание и заглавная буква имен параметров также взяты из синтаксиса. Это не влияет на имя параметра, указанное ключевым словом .Parameter.

Общие параметры

Общие параметры добавляются в синтаксис и список параметров раздела справки, даже если они не влияют. Дополнительные сведения о распространенных параметрах см. в about_CommonParameters.

Таблица атрибутов параметров

Get-Helpсоздает таблицу атрибутов параметров, которая отображается при использовании параметра Full или Get-Help . Значение атрибутов значения "Обязательный", "Позиция" и "Значение по умолчанию" берется из синтаксиса функции или скрипта.

Значения по умолчанию и значение для "Принимать подстановочные знаки" не отображаются в таблице атрибутов параметров, даже если они определены в функции или скрипте. Чтобы помочь пользователям, укажите эти сведения в описании параметра.

Замечания

Раздел "Примечания " раздела справки автоматически создается из имени функции или скрипта. Вы не можете изменить или повлиять на его содержимое.

Примеры

Справка на основе комментариев для функции

Следующая пример функции включает справку на основе комментариев:

function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
$name = $name + "." + $extension
$name

<#
.SYNOPSIS

Adds a file name extension to a supplied name.

.DESCRIPTION

Adds a file name extension to a supplied name.
Takes any strings for the file name or extension.

.PARAMETER Name
Specifies the file name.

.PARAMETER Extension
Specifies the extension. "Txt" is the default.

.INPUTS

None. You can't pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension
or file name.

.EXAMPLE

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

Результаты будут следующими:

Get-Help -Name "Add-Extension" -Full

NAME

Add-Extension

SYNOPSIS

Adds a file name extension to a supplied name.

SYNTAX

Add-Extension [[-Name] <String>] [[-Extension] <String>]
[<CommonParameters>]

DESCRIPTION

Adds a file name extension to a supplied name. Takes any strings for the
file name or extension.

PARAMETERS

-Name
Specifies the file name.

Required?                    false
Position?                    0
Default value
Accept pipeline input?       false
Accept wildcard characters?

-Extension
Specifies the extension. "Txt" is the default.

Required?                    false
Position?                    1
Default value
Accept pipeline input?       false
Accept wildcard characters?

<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type
"get-help about_commonparameters".

INPUTS
None. You can't pipe objects to Add-Extension.

OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

Example 1

PS> extension -name "File"
File.txt

Example 2

PS> extension -name "File" -extension "doc"
File.doc

Example 3

PS> extension "File" "doc"
File.doc

RELATED LINKS

http://www.fabrikam.com/extension.html
Set-Item

Описание параметров в синтаксисе функции

Этот пример аналогичен предыдущему, за исключением того, что описания параметров вставляются в синтаксис функции. Этот формат наиболее полезен при кратком выполнении описаний.

function Add-Extension
{
param
(

[string]
#Specifies the file name.
$name,

[string]
#Specifies the file name extension. "Txt" is the default.
$extension = "txt"
)

$name = $name + "." + $extension
$name

<#
.SYNOPSIS

Adds a file name extension to a supplied name.

.DESCRIPTION

Adds a file name extension to a supplied name. Takes any strings for the
file name or extension.

.INPUTS

None. You can't pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

.EXAMPLE

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

Справка на основе комментариев для скрипта

Следующий пример сценария включает справку на основе комментариев. Обратите внимание на пустые строки между закрытием #> и оператором Param . В скрипте, который не содержит инструкции Param, между окончательным комментарием в разделе справки и первым объявлением функции должно быть не менее двух пустых строк. Без этих пустых строк Get-Help связывает раздел справки с функцией, а не скриптом.

<#
.SYNOPSIS

Performs monthly data updates.

.DESCRIPTION

The Update-Month.ps1 script updates the registry with new data generated
during the past month and generates a report.

.PARAMETER InputPath
Specifies the path to the CSV-based input file.

.PARAMETER OutputPath
Specifies the name and path for the CSV-based output file. By default,
MonthlyUpdates.ps1 generates a name from the date and time it runs, and
saves the output in the local directory.

.INPUTS

None. You can't pipe objects to Update-Month.ps1.

.OUTPUTS

None. Update-Month.ps1 doesn't generate any output.

.EXAMPLE

PS> .\Update-Month.ps1

.EXAMPLE

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

.EXAMPLE

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath `
C:\Reports\2009\January.csv
#>

param ([string]$InputPath, [string]$OutPutPath)

function Get-Data { }
...

Следующая команда получает справку по скрипту. Так как скрипт не находится в каталоге, который указан в переменной среды $env:Path, команда Get-Help, которая получает справку по скрипту, должна указать путь к скрипту.

Get-Help -Name .\update-month.ps1 -Full

# NAME

C:\ps-test\Update-Month.ps1

# SYNOPSIS

Performs monthly data updates.

# SYNTAX

C:\ps-test\Update-Month.ps1 [-InputPath] <String> [[-OutputPath]
<String>] [<CommonParameters>]

# DESCRIPTION

The Update-Month.ps1 script updates the registry with new data
generated during the past month and generates a report.

# PARAMETERS

-InputPath
Specifies the path to the CSV-based input file.

Required?                    true
Position?                    0
Default value
Accept pipeline input?       false
Accept wildcard characters?

-OutputPath
Specifies the name and path for the CSV-based output file. By
default, MonthlyUpdates.ps1 generates a name from the date
and time it runs, and saves the output in the local directory.

Required?                    false
Position?                    1
Default value
Accept pipeline input?       false
Accept wildcard characters?

<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type,
"get-help about_commonparameters".

# INPUTS

None. You can't pipe objects to Update-Month.ps1.

# OUTPUTS

None. Update-Month.ps1 doesn't generate any output.

Example 1

PS> .\Update-Month.ps1

Example 2

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

Example 3

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath
C:\Reports\2009\January.csv

# RELATED LINKS

Перенаправление в XML-файл

Содержимое справки на основе XML можно написать для функций и скриптов. Хотя помощь, основанная на комментариях, удобнее реализовать, для обновляемой справки и предоставления содержимого справки на нескольких языках требуется справка, основанная на XML.

В следующем примере показаны первые несколько строк скрипта Update-Month.ps1. Скрипт использует ключевое .EXTERNALHELP слово для указания пути к разделу справки на основе XML для скрипта.

Обратите внимание, что значение ключевого .EXTERNALHELP слова отображается в той же строке, что и ключевое слово. Любое другое размещение неэффективно.

# .EXTERNALHELP C:\MyScripts\Update-Month-Help.xml

param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...

В следующих примерах показаны три допустимых размещения ключевого .EXTERNALHELP слова в функции.

function Add-Extension {
    # .EXTERNALHELP C:\ps-test\Add-Extension.xml

    param ([string] $name, [string]$extension = "txt")
    $name = $name + "." + $extension
    $name
}

function Add-Extension {
    param ([string] $name, [string]$extension = "txt")
    $name = $name + "." + $extension
    $name

    # .EXTERNALHELP C:\ps-test\Add-Extension.xml
}

# .EXTERNALHELP C:\ps-test\Add-Extension.xml
function Add-Extension {
    param ([string] $name, [string]$extension = "txt")
    $name = $name + "." + $extension
    $name
}

Перенаправление в другой раздел справки

Следующий код является фрагментом из начала встроенной функции справки в PowerShell, которая отображает один экран справки одновременно. Так как раздел справки для Get-Help командлета описывает функцию справки, функция справки использует .ForwardHelpTargetName ключевые слова и .ForwardHelpCategory ключевые слова для перенаправления пользователя в раздел справки командлета Get-Help .

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

    [CmdletBinding(DefaultParameterSetName='AllUsersView')]
    param(
        [Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
        [System.String]
        ${Name},
    ...

Следующая команда использует эту функцию:

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...

См. также

about_Functions
about_Functions_Advanced_Parameters
about_Scripts
написание Comment-Based справочного содержания

Поделиться через