about_Comment_Based_Help

Статья
05/09/2024

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

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

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

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

Командлет 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 ключевое слово предшествует описанию функции или скрипта.

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

.COMPONENT

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

.ROLE

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

.FUNCTIONALITY

Ключевые слова, описывающие предполагаемое использование функции. Параметр 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 имеет приоритет над другими ключевыми словами справки на основе комментариев. При .ExternalHelp наличии Get-Help справки на основе комментариев не отображается, даже если не удается найти раздел справки, соответствующий значению .ExternalHelp ключевое слово.

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

<ScriptModule.psm1>-help.xml

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

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

Автоматически созданное содержимое

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

Имя

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

Синтаксис

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

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

Список параметров в разделе справки создается на основе синтаксиса функции или скрипта, а также из описаний, добавляемых с помощью .Parameter ключевое слово. Параметры функции отображаются в разделе Параметры раздела справки в том же порядке, что и в синтаксисе функции или скрипта. Написание и прописные буквы имен параметров также взяты из синтаксиса. Имя параметра, указанное .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 { }
...

Следующая команда получает справку по скрипту. Так как скрипт не находится в каталоге, указанном в переменной $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.
...

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