о_помощь_на_основе_комментариев

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

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

Длинное описание

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

Командлет 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 также может включать универсальный идентификатор ресурса (URI) на онлайн-версию той же темы справки. Веб-версия открывается при использовании параметра Online для Get-Help. URI должен начинаться с http или https.

`.COMPONENT`

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

`.ROLE`

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

`.FUNCTIONALITY`

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

`.FORWARDHELPTARGETNAME <Command-Name>`

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

# .FORWARDHELPTARGETNAME <Command-Name>

`.FORWARDHELPCATEGORY`

Указывает категорию справки элемента в .FORWARDHELPTARGETNAME. Допустимые значения: Alias, Cmdlet, HelpFile, Function, Provider, General, FAQ, Glossary, ScriptCommand, ExternalScript, Filterили All. Используйте это ключевое слово, чтобы избежать конфликтов при наличии команд с тем же именем.

# .FORWARDHELPCATEGORY <Category>

`.REMOTEHELPRUNSPACE <PSSession-variable>`

Указывает сеанс, содержащий раздел справки. Введите переменную, содержащую объект 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-файла справки для функции. Начиная с PowerShell 5.0 функции, экспортируемые модулем, можно задокументировать в файле справки, который называется для модуля. Не нужно использовать .EXTERNALHELP ключевое слово примечания. Например, если Test-Function функция экспортируется MyModule модулем, можно указать файл MyModule-help.xmlсправки. Командлет Get-Help ищет справку по Test-Function функции в файле в MyModule-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> Add-Extension -Name "File"
File.txt

.EXAMPLE

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

.EXAMPLE

PS> Add-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> Add-Extension -Name "File"
File.txt

Example 2

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

Example 3

PS> Add-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> Add-Extension -Name "File"
File.txt

.EXAMPLE

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

.EXAMPLE

PS> Add-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.
...

См. также

О_функциях
о_Функциях_Расширенные_Параметры
о_Скриптах
написание Comment-Based справки содержимого

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-05-21