Любой хорошо написанный скрипт должен содержать справочную информацию о себе. Справочная информация должна содержать как минимум:
Я видел множество вариантов оформления справки. Самые популярные это:
Я не буду останавливаться на том, как это всё выглядит, а лишь расскажу, как должна быть оформлена справка к команде. Windows PowerShell предлагает нам 2 пути.
Справка, оформленная специальным образом в виде встроенного блока комментариев. Специальным образом — чтобы можно было её прочитать не только из тела самого скрипта, но и через стандартный командлет 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 <ParameterName> | Описание к каждому параметру. |
.Example | Пример использования функции и описание примера (т.е. что произойдёт, если выполнить конкретный пример). |
.Inputs | Тип данных, которые принимаются функцией. Например, [System.String]. Если их несколько, можете указать несколько типов на одной или нескольких строках. |
.Outputs | Тип возвращаемых данных. Например, [IO.FileInfo] Если функция может возвращать несколько разных типов, их можно указать на одной или нескольких строках. |
.Notes | Здесь можно указать какие-то заметки. Например, я использую .Notes для указания автора кода и его адреса. |
.Link | Можно указать какие-то связанные ссылки. Например, на связанные команды. |
.Component | Можно указать продукт или компонент, для которого предназначена конкретная функция. Скажем, это может быть PKI, Exchange, SQL, SharePoint и т.д. |
.Role | Указывает роль пользователя, который выполняет код. В принципе, можно указать необходимые права и/или привилегии. |
.Functionality | Тоже можно что-то написать. Но я не вижу особой разницы с Description. |
.ForwardHelpTargetName | Указывает команду, на которую надо форвардить пользователя при вызове справки. Т.е. если вы считаете, что в другом командлете/функции справка описана лучше, чем у вас (и по этой же теме), можете сослать пользователя туда. На практике это применяется, когда вы делаете proxy-функции. Т.е. реализуете функционал родного командлета и немного изменяете его под конкретные нужды. |
.ForwardHelpCategory | Если указали предыдущий тег, надо указать конкретный раздел справки командлета, на который ссылаетесь. |
.RemoteHelpRunspace | Можно указать имя переменной, которая хранит данные об удалённой сессии (pssession) для поиска хелпа. Маловероятно, что он вам понадобится |
.ExternalHelp | Данный тэг используется для ссылки на внешний файл справки в формате XML. Об этом будет написано ниже. |
По собственному опыту могу сказать, что все их заполнять не обязательно (хотя и желательно указать максимальное количество необходимой информации). Как минимум, справка должна содержать следующие секции справки: Synopsis, Description, Parameter, Example. Остальное по желанию.
Внешняя справка — это альтернативный вариант оформления справки. Если первый вариант использует специально оформленный блок комментариев в коде, второй использует внешний файл 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.
Comments: