about_Comment_Based_Help

Статья
10/04/2023

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

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

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

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

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

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

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

Командлеты 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>
#>

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

В модуле .psm1скрипта справка на основе комментариев использует синтаксис для функций, а не синтаксис для сценариев. Синтаксис скрипта нельзя использовать для предоставления справки для всех функций, определенных в модуле скрипта.

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

# .ExternalHelp <XML-file-name>
function <function-name>
{
  ...
}

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

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

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

.COMPONENT

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

.ROLE

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

.FUNCTIONALITY

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

.FORWARDHELPTARGETNAME

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

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORY

Указывает категорию справки элемента в .ForwardHelpTargetName. Допустимые значения: Alias, Cmdlet, FunctionGeneralFAQProviderHelpFileScriptCommandExternalScriptGlossaryFilterили .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создает таблицу атрибутов параметров, которая отображается при использовании параметра Get-HelpFull или Parameter . Значение атрибутов значения "Обязательный", "Позиция" и "Значение по умолчанию" берется из синтаксиса функции или скрипта.

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

Замечания

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

Примеры

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

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

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 cannot 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 cannot 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 cannot 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 cannot pipe objects to Update-Month.ps1.

.OUTPUTS

None. Update-Month.ps1 does not 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 cannot pipe objects to Update-Month.ps1.

# OUTPUTS

None. Update-Month.ps1 does not 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.
...

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