about_Comment_Based

РАЗДЕЛ
about_Comment_Based_Help

КРАТКОЕ ОПИСАНИЕ
Описание написания разделов справки на основе комментариев для
функций и скриптов.

ПОЛНОЕ ОПИСАНИЕ
С помощью специальных ключевых слов комментариев справки можно
писать разделы справки на основе комментариев для функций и скриптов.

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

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

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

СИНТАКСИС ДЛЯ СПРАВКИ НА ОСНОВЕ КОММЕНТАРИЕВ
Синтаксис для справки на основе комментариев имеет следующий вид.
# .< ключевое_слово_справки>
# <содержимое_справки>

-или:

<#
.< ключевое_слово_справки>
< содержимое_справки>
#>

Справка на основе комментариев пишется как набор комментариев.
Можно вводить символ комментария (#) перед каждой строкой
комментариев или использовать символы "<#" и "#>" для создания
блока комментариев. Все строки, входящие в блок комментариев,
воспринимаются как комментарии.

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

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

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

<#
.Description
Get-Function отображает имя и синтаксис всех функций в
рамках сеанса.
#>

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

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

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

-- В начале тела функции.

-- В конце тела функции.

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

Пример:

function MyFunction
{
<#
.< ключевое_слово_справки>
< содержимое_справки>
#>

<команды функции>
}

-или:

function MyFunction
{
<команды функции>

<#
.< ключевое_слово_справки>
< содержимое_справки>
#>
}

-или:

<#
.< ключевое_слово_справки>
< содержимое_справки>
#>
function MyFunction { }

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

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

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

-- Если первый элемент тела скрипта (после справки) является
объявлением функции, между последней строкой справки для
скрипта и объявлением функции должны присутствовать хотя бы
две пустых строки. В противном случае справка интерпретируется
как справка для функции, а не справка для скрипта.

-- В конце файла скрипта.

Пример:

<#
.< ключевое_слово_справки>
< содержимое_справки>
#>

function MyFunction { }

-или-

function MyFunction { }

<#
.< ключевое_слово_справки>
< содержимое_справки>
#>

КЛЮЧЕВЫЕ СЛОВА СПРАВКИ НА ОСНОВЕ КОММЕНТАРИЕВ
Ниже перечислены действительные ключевые слова справки на основе
комментариев. Перечисленные выполнено в том порядке, в котором
ключевые слова обычно появляются в разделе справки, для всех
ключевых слов приведено краткое описание.
Эти ключевые слова могут появляться в справке на основе
комментариев в любом порядке, регистр символов не имеет значения.

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

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

.PARAMETER <имя_параметра>
Описание параметра. Ключевое слово Parameter может
указываться для каждого из параметров функции или скрипта.

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

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

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

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

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

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

.LINK
Имя связанного раздела. Это ключевое слово необходимо
повторить для каждого связанного раздела.

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

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

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

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

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

.FORWARDHELPTARGETNAME <имя_команды>
Обеспечивает перенаправление в раздел справки для указанной
команды. Можно выполнять перенаправление пользователей в
любой раздел справки, включая разделы справки для функции,
скрипта, командлета или поставщика.

.FORWARDHELPCATEGORY <категория>
Задает категорию справки элемента в ForwardHelpTargetName.
Допустимыми значениями являются Alias, Cmdlet, HelpFile,
Function, Provider, General, FAQ, Glossary, ScriptCommand,
ExternalScript, Filter или All. Используйте это ключевое
слово для предотвращения конфликтов при появлении команд с
одинаковыми именами.

.REMOTEHELPRUNSPACE <переменная_сеанса_PSSession>
Задает сеанс, в котором содержится раздел справки. Введите
переменную, которая содержит сеанс PSSession. Это ключевое
слово используется командлетом Export-PSSession для поиска
разделов справки для экспортируемых команд.

.EXTERNALHELP <путь_к_XML-файлу_справки>
Задает путь к файлу справки на основе XML для скрипта или
функции.

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

Дополнительные сведения о формате файлов справки для
командлетов на основе XML см. в разделе "How to Write Cmdlet
Help" (Как писать справку для командлетов) в библиотеке MSDN
по адресу http://go.microsoft.com/fwlink/?LinkID=123415.

АВТОМАТИЧЕСКИ СГЕНЕРИРОВАННОЕ СОДЕРЖИМОЕ
Имя, синтаксис, список параметров, таблица атрибутов параметров,
общие параметры и примечания автоматически генерируются
командлетом Get-Help.

Имя:
Подраздел "Имя" раздела справки для функции заполняется
именем функции из синтаксиса функции. Подраздел "Имя"
раздела справки для скрипта заполняется именем файла
скрипта. Для изменения имени или преобразования его в
верхний реестр измените синтаксис функции или имя файла
скрипта.

Синтаксис:
Подраздел "Синтаксис" раздела справки для функции
генерируется в соответствии с информацией о синтаксисе
функции или скрипта. Чтобы добавить подробную информацию
в раздел справки "Синтаксис", например тип данных
платформы .NET параметра, добавьте эту информацию в
синтаксис. Если тип параметра не указан, по умолчанию
используется значение типа "Объект".

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

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

Таблица атрибутов параметров:
Командлет Get-Help генерирует таблицу атрибутов
параметров, которая отображается при использовании
параметров Full или Parameter командлета Get-Help.
Значения атрибутов "Необходимый", "Позиция" и "Значение
по умолчанию" основаны на синтаксисе функции или скрипта.

Примечания:
Подраздел "Примечания" раздела справки для функции
автоматически генерируется в соответствии с именем
функции или скрипта. Невозможно изменить содержимое этого
раздела или воздействовать на него.

ПРИМЕРЫ

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

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

function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
$name = $name + "." + $extension $name

<#
.SYNOPSIS
Добавление расширения имени файла к переданному на вход имени.

.DESCRIPTION
Добавление расширения имени файла к переданному на вход
имени. Принимает любые строки в качестве имени файла или
расширения.

.PARAMETER Name
Задает имя файла.

.PARAMETER Extension
Задает расширение. По умолчанию используется расширение "Txt".

.INPUTS
Нет. Объекты не могут передаваться функции Add-Extension
по конвейеру.

.OUTPUTS
System.String. Функция Add-Extension возвращает строку с
расширением или именем файла.

.EXAMPLE
C:\PS> extension -name "файл"
файл.txt

.EXAMPLE
C:\PS> extension -name "файл" -extension "doc"
файл.doc

.EXAMPLE
C:\PS> extension "файл" "doc"
файл.doc

.LINK
Интернет-версия: http://www.fabrikam.com/extension.html

.LINK
Set-Item
#>
}

Результаты выглядят следующим образом:

C:\PS> get-help add-extension -full

ИМЯ
Add-Extension

ОПИСАНИЕ
Добавление расширения имени файла к переданному на вход имени.

СИНТАКСИС
Add-Extension [[-Name] <String>] [[-Extension] <String>]
[<CommonParameters>]
ОПИСАНИЕ
Добавление расширения имени файла к переданному на вход
имени. Принимает любые строки в качестве имени файла или
расширения.

ПАРАМЕТРЫ
-Name
Задает имя файла.

Требуется? false
Позиция? 0
Значение по умолчанию
Принимать входные
данные с конвейера? false
Принимать подстановочные знаки?

-Extension
Задает расширение. По умолчанию используется
расширение "Txt".

Требуется? false
Позиция? 1
Значение по умолчанию
Принимать входные данные
с конвейера? false
Принимать подстановочные знаки?

<CommonParameters>
Данный командлет поддерживает общие параметры:
-Verbose, -Debug, ErrorAction, -ErrorVariable,
-WarningAction, -WarningVariable, OutBuffer и
-OutVariable. Чтобы получить дополнительные
сведения, введите команду "get-help
about_commonparameters".

ВХОДНЫЕ ДАННЫЕ
Нет. Объекты не могут передаваться функции Add-Extension
по конвейеру.

ВЫХОДНЫЕ ДАННЫЕ
System.String. Функция Add-Extension возвращает строку с
расширением или именем файла.

-------------------------- ПРИМЕР 1 --------------------------
C:\PS> extension -name "файл"
файл.txt

-------------------------- ПРИМЕР 2 --------------------------
C:\PS> extension -name "файл" -extension "doc"
файл.doc

-------------------------- ПРИМЕР 3 --------------------------
C:\PS> extension "файл" "doc"
файл.doc

ССЫЛКИ ПО ТЕМЕ
Интернет-версия: http://www.fabrikam.com/extension.ht
ml Set-Item

Пример 2. Описание параметров в коде функции

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

function Add-Extension
{
param
(
[string]
# Задает имя файла.
$name,

[string]
# Задает расширение. По умолчанию используется
расширение "Txt".
$extension = "txt"
)
$name = $name + "." + $extension
$name

<#
.SYNOPSIS
Добавление расширения имени файла к переданному на вход имени.

.INPUTS
Нет. Объекты не могут передаваться функции Add-Extension
по конвейеру.

.OUTPUTS
System.String. Функция Add-Extension возвращает строку с
расширением или именем файла.

.EXAMPLE
C:\PS> extension -name "файл"
файл.txt

.EXAMPLE
C:\PS> extension -name "файл" -extension "doc"
файл.doc

.EXAMPLE
C:\PS> extension "файл" "doc"
файл.doc

.LINK
Интернет-версия: http://www.fabrikam.com/extension.html

.LINK
Set-Item
#>
}

Пример 3. Справка для скрипта на основе комментариев

В следующем примере в код скрипта включена справка на основе
комментариев.

Обратите внимание на пустые строки между закрывающим
элементом "#>" и оператором Param. Если в скрипте нет
оператора Param, между последней строкой последнего
комментария и первой строкой объявления первой функции должны
присутствовать хотя бы две пустых строки. Без этих пустых
строк Get-Help свяжет раздел справки с функцией, а не со скриптом.

<#
.SYNOPSIS
Выполняет ежемесячное обновление данных.

.DESCRIPTION
Скрипт Update-Month.ps1 обновляет реестр, дополняя его
новыми данными, созданными в течение прошедшего месяца, и
генерирует отчет.

.PARAMETER InputPath
Задает путь к входному CSV-файлу.

.PARAMETER OutputPath
Задает имя и путь к выходному CSV-файлу. По умолчанию
MonthlyUpdates.ps1 формирует имя в соответствии с датой и
временем запуска и сохраняет выходные данные в локальном
каталоге.

.INPUTS
Нет. Объекты не могут передаваться скрипту Update-Month.ps1
по конвейеру.

.OUTPUTS
Нет. Update-Month.ps1 не формирует никаких выходных данных.

.EXAMPLE
C:\PS> .\Update-Month.ps1

.EXAMPLE
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

.EXAMPLE
C:\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, которая возвращает справку к
скрипта, необходимо указать путь к скрипту.

PS C:\ps-test> get-help .\update-month.ps1 -full

NAME
C:\ps-test\Update-Month.ps1

SYNOPSIS
Выполняет ежемесячное обновление данных.

СИНТАКСИС
C:\ps-test\Update-Month.ps1 [-InputPath] <String>
[[-OutputPath] ]<String>] [<CommonParameters>]

ОПИСАНИЕ
Скрипт Update-Month.ps1 обновляет реестр, дополняя
его новыми данными, созданными в течение прошедшего
месяца, и генерирует отчет.

ПАРАМЕТРЫ
-InputPath
Задает путь к входному CSV-файлу.

Требуется? true
Позиция? 0
Значение по умолчанию
Принимать входные данные
с конвейера? false
Принимать подстановочные знаки?

-OutputPath
Задает имя и путь к выходному CSV-файлу. По умолчанию
MonthlyUpdates.ps1 формирует имя в соответствии с датой
и временем запуска и сохраняет выходные данные в
локальном каталоге.

ВХОДНЫЕ ДАННЫЕ
Нет. Объекты не могут передаваться скрипту
Update-Month.ps1 по конвейеру.

ВЫХОДНЫЕ ДАННЫЕ
Нет. Update-Month.ps1 не формирует никаких
выходных данных.

-------------------------- ПРИМЕР 1 --------------------------

C:\PS> .\Update-Month.ps1

-------------------------- ПРИМЕР 2 --------------------------

C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

-------------------------- ПРИМЕР 3 --------------------------

C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
-outputPath
C:\Reports\2009\January.csv

ССЫЛКИ ПО ТЕМЕ

Пример 4. Перенаправление в XML-файл

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

В следующем примере показаны несколько первых строк скрипта
Update-Month.ps1. В скрипте используется ключевое слово
ExternalHelp, позволяющее указать путь к разделу справки для
скрипта на основе XML.

# .ExternalHelp C:\MyScripts\Update-Month-Help.xml

param ([string]$InputPath, [string]$OutPutPath)

function Get-Data { }
...

В следующем примере показано использование ключевого слова
ExternalHelp в функции.

function Add-Extension
{
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension $name

# .ExternalHelp C:\ps-test\Add-Extension.xml
}

Пример 5. Перенаправление в другой раздел справки

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

Эта функция используется в следующей команде.

C:\PS> get-help help

ИМЯ
Get-Help

ОПИСАНИЕ
Отображает сведения о командлетах и концепциях
Windows PowerShell.
...

СМ. ТАКЖЕ
about_Functions
about_Functions_Advanced_Parameters
about_Scripts
"Написание справки для командлетов" (http://go.microsoft.com/fwlink/?LinkID=123415)