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

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

  • Статья

КРАТКОЕ ОПИСАНИЕ

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

ПОДРОБНОЕ ОПИСАНИЕ

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

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

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

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

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

СИНТАКСИС ДЛЯ СПРАВКИ НА ОСНОВЕ КОММЕНТАРИЕВ

Ниже приведен синтаксис справки на основе комментариев.

.<help keyword>
<help content>

или

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

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

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

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

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

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

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

СИНТАКСИС ДЛЯ СПРАВКИ НА ОСНОВЕ КОММЕНТАРИЕВ В ФУНКЦИЯХ

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

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

Пример:

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>
{
  ...
}

КЛЮЧЕВЫЕ СЛОВА СПРАВКИ НА ОСНОВЕ КОММЕНТАРИЕВ

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

. ОБЗОР

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

. ОПИСАНИЕ

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

. ПАРАМЕТР

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

Введите имя параметра в той же строке, что и . КЛЮЧЕВОЕ СЛОВО PARAMETER". Введите описание параметра в строках после . КЛЮЧЕВОЕ СЛОВО PARAMETER". Windows PowerShell интерпретирует весь текст между ". СТРОКА PARAMETER" и следующая ключевое слово или конец блока комментариев в рамках описания параметра. Описание может включать разрывы абзаца.

.PARAMETER  <Parameter-Name>

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

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

. ПРИМЕРЕ

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

. ВХОДЫ

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

. ВЫХОДЫ

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

. ЗАМЕТКИ

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

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

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

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

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

. КОМПОНЕНТ

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

. РОЛЬ

Роль пользователя для раздела справки. Это содержимое отображается, Get-Help если команда включает параметр Role для Get-Help.

. ФУНКЦИОНАЛЬНОСТЬ

Предполагаемое использование функции. Это содержимое отображается, Get-Help если команда включает параметр Функциональные возможности .Get-Help

. FORWARDHELPTARGETNAME

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

# .FORWARDHELPTARGETNAME <Command-Name>

. FORWARDHELPCATEGORY

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

# .FORWARDHELPCATEGORY <Category>

. REMOTEHELPRUNSPACE

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

# .REMOTEHELPRUNSPACE <PSSession-variable>

. EXTERNALHELP

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

# .EXTERNALHELP <XML Help File>

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

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

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

<ScriptModule.psm1>-help.xml

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

Дополнительные сведения о формате справки по командлетам на основе XML см. в статье How to Write Cmdlet Help in the MSDN library.

АВТОМАТИЧЕСКИ СОЗДАННОЕ СОДЕРЖИМОЕ

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

Имя

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

Синтаксис

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

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

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

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

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

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

Get-Help создает таблицу атрибутов параметров, которая отображается при использовании параметра Full или Parameter объекта Get-Help. Значение атрибутов "Required", "Position" и "Default" взято из синтаксиса функции или скрипта.

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

Комментарии

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

Примеры

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

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

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 { }
...

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

Get-Help -Path .\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.
...

СМ. ТАКЖЕ

about_Functions

about_Functions_Advanced_Parameters

about_Scripts

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