Любой хорошо написанный скрипт должен содержать справочную информацию о себе. Справочная информация должна содержать как минимум:

• Целевое назначение скрипта/команды.
• Описание параметров и правила их использования.
• Один или несколько примеров использования скрипта/команды.

Я видел множество вариантов оформления справки. Самые популярные это:

• Комментарий перед параметром.
• Выделенный блок комментариев, где приводится какая-то справка по использованию в произвольном исполнении.
• Отсутствие какой-либо справки вообще.

Я не буду останавливаться на том, как это всё выглядит, а лишь расскажу, как должна быть оформлена справка к команде. Windows PowerShell предлагает нам 2 пути.

Comment-based help

Справка, оформленная специальным образом в виде встроенного блока комментариев. Специальным образом — чтобы можно было её прочитать не только из тела самого скрипта, но и через стандартный командлет Get-Help. Если мы посмотрим на вывод командлета Get-Help, мы увидим, что вся справка разбита на категории/секции — описание, детальное описание, параметры, примеры и т.д. То же самое разделение используется и при оформлении справки в коде. Вот как выглядит общий шаблон справки:

function Remove-File {
<#
.Synopsis
    Removes the specified command.
.Description
    The Remove-File cmdlet removes one or more files.
.Parameter Path
    Specifies the path to a file.
.Parameter Force
    Supresses all confirmation prompts.
.Example
    Remove-File c:\pagefile.sys
    
    Removes pagefile.sys file from C:\ drive
.Inputs
    System.String
.Link
    http://www.contoso.com/
#>
[CmdletBinding()]
    param (
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
        [string]$Path,
        [switch]$Force
    )
    # располагаем основной код
}

Примечание: блок встроенной справки должен располагаться либо в самом начале функции (на следующей строке после первой открывающейся фигурной скобки) или в самом конце (перед последней закрывающейся фигурной скобкой). Я предпочитаю её размещать в начале.

Уже на данном этапе мы можем вставить код в консоль и выполнить 'Get-Help Remove-File' и получите знакомую справку. При этом, все дополнительные параметры (-Full, –Detailed, –Examples, etc.) так же доступны. Точка и слово на ней означает категорию или тэг. На следующей строке размещается текст, связанный с конкретным тэгом. Некоторые тэги могут быть использованы несколько раз — .Example и .Parameter. .Example применяется столько раз, сколько у вас используется примеров. Если 5 примеров, тэг .Example должен быть использован 5 раз. То же самое касается и .Parameter — на каждый параметр определённый в скрипте должен быть использован тэг Parameter. После ключевого слова .Parameter должно следовать имя параметра на этой же строке. Полный список возможных тэгов приводится в следующей таблице:

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

External Help

Внешняя справка — это альтернативный вариант оформления справки. Если первый вариант использует специально оформленный блок комментариев в коде, второй использует внешний файл XML. Я не буду расписывать схему и структуру этого XML, просто расскажу как его можно создать и когда его лучше всего использовать.

Справку к командам в отдельном файле можно создать при помощи CmdLet Help Editor.

Замтека: этот редактор достаточно бажный и нередко вылетает с разными ошибками. Поэтому периодически сохраняйте свои изменённые данные.

Если для одиночных функций удобней всего пользоваться справкой, встроенной в код, то для больших проектов (например, у вас модуль с кучей функций) есть смысл держать всю справку в отдельном файле. Например, вы можете распотрошить мой PowerShell PKI Module и посмотреть, как оно выглядит. В каждой функции я делаю ссылку на PKI.Help.xml, который уже хранит справку для всех функций, доступных в модуле. Т.е. если вы справку держите в отдельном XML, то в коде функции вам надо сделать ссылку на этот XML:

function Remove-File {
<#
.ExternalHelp File.xml
#>
[CmdletBinding()]
    param (
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
        [string]$Path,
        [switch]$Force
    )
    # располагаем основной код
}

Заметка: если у кого-то из вас осталась самая первая версия (0.8) PowerShell PKI модуля, можете увидеть, что там используется ещё comment-based help, а в более новых уже XML.

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