about_Comment_Based_Help
Краткое описание
Описывает, как писать разделы справки на основе комментариев для функций и скриптов.
Подробное описание
Вы можете написать разделы справки на основе комментариев для функций и сценариев с помощью специальных ключевое слово справки.
Командлет Get-Help отображает справку на основе комментариев в том же формате, в котором отображаются разделы справки командлета, созданные из XML-файлов. Пользователи могут использовать все параметрыGet-Help
, такие как "Подробные", "Полные", "Примеры" и "Интернет", для отображения содержимого справки на основе комментариев.
Вы также можете создавать файлы справки на основе XML для функций и скриптов. Чтобы разрешить Get-Help
командлету найти XML-файл справки для функции или скрипта, используйте .ExternalHelp
ключевое слово. Без этого ключевое слово Get-Help
не удается найти разделы справки на основе XML для функций или скриптов.
В этом разделе объясняется, как писать разделы справки для функций и сценариев. Сведения о том, как отображать разделы справки для функций и сценариев, см. в разделе "Справка".
Командлеты Update-Help и Save-Help работают только в XML-файлах. Обновляемая справка не поддерживает разделы справки на основе комментариев.
Синтаксис справки на основе комментариев
Синтаксис справки на основе комментариев выглядит следующим образом:
# .<help keyword>
# <help content>
or
<#
.<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
}
or
function Get-Function
{
# function logic
<#
.<help keyword>
<help content>
#>
}
or
<#
.<help keyword>
<help content>
#>
function Get-Function { }
Синтаксис справки на основе комментариев в скриптах
Справка на основе комментариев для скрипта может отображаться в одном из следующих двух расположений в скрипте.
В начале файла скрипта. Справка по скрипту может предшествовать только примечаниям и пустым строкам.
Если первый элемент в тексте скрипта (после справки) является объявлением функции, между концем справки скрипта и объявлением функции должно быть не менее двух пустых строк. В противном случае справка интерпретируется как справка для функции, а не справка по скрипту.
В конце файла сценария. Однако если скрипт подписан, поместите справку на основе комментариев в начале файла скрипта. Конец скрипта занят блоком подписи.
Например:
<#
.<help keyword>
<help content>
#>
function Get-Function { }
or
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-Help
Online . Универсальный код ресурса (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
, Function
General
FAQ
Provider
HelpFile
ScriptCommand
ExternalScript
Glossary
Filter
или .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-Help
Full или Parameter . Значение атрибутов значения "Обязательный", "Позиция" и "Значение по умолчанию" берется из синтаксиса функции или скрипта.
Значения по умолчанию и значение для символов Accept Wild карта не отображаются в таблице атрибутов параметров, даже если они определены в функции или скрипте. Чтобы помочь пользователям, укажите эти сведения в описании параметра.
Замечания
Раздел "Примечания " раздела справки автоматически создается из имени функции или скрипта. Вы не можете изменить или повлиять на его содержимое.
Примеры
Справка на основе комментариев для функции
Следующая пример функции включает справку на основе комментариев:
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.
...
См. также
PowerShell