Windows PowerShell: Создание справочной системы с помощью комментариев

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

Дон Джонс

Одна из самых замечательных вещей в Windows PowerShell — справочная система. Справка содержит информацию о синтаксисе, подробные объяснения, примеры и т. п.

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

При создании собственных команд как функций и сценариев нужно придерживаться того же аккуратного стиля, которым отличаются стандартные командлеты Windows PowerShell. Нужно стараться, чтобы ваша работа максимально отвечала стандартам оболочки. Один из стандартов — подготовка и предоставление справки.

Можно создать точно такие же файлы справки на основе XML, которые используются в Windows PowerShell. Подробнее эта тема обсуждается в моей самостоятельно опубликованной книге «Windows PowerShell Scripting and Toolmaking». Однако большинству из вас не потребуется вся гибкость, предоставляемая этими файлами справки, например возможность предоставления справки на многих языках.

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

Правила справки на основе комментариев

Правил создания справки на основе комментариев немного, поэтому я сформулирую их здесь.

• Обычно специальные блоки комментария заключаются в специальные маркеры комментария: <# и #>. Также можно единичные строки комментария отмечать символом «решетка» (#).
• Комментарии для справки должны размещаться в самом начале файла сценария. Предпочтительнее размещать справку в функции, а не перед ней. Это позволяет хранить комментарии в функции и гарантирует, что Windows PowerShell не спутает их с чем-нибудь еще. Ничто не препятствует размещению справки в виде комментариев в конце файла, но мне не нравится это делать, потому что это умаляет другие преимущества справки на основе комментариев.
• Если вы предоставляете справку для функции, блок справки на основе комментариев должен размещаться непосредственно перед или сразу же после имени функции и открывающей фигурной скобки.
• При размещении в сценарии нескольких функций, например в модуле сценариев, вы можете предоставить справку для файла путем размещения блока комментариев вверху. Добавьте перед комментарием как минимум несколько пустых строк, чтобы гарантировано отделить справку функции.
• Если ошибиться в любом из ключевых слов справки на основе комментариев, Windows PowerShell может проигнорировать весь блок. Поэтому надо следить за правописанием, потому что это важно.

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

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

<# .SYNOPSIS Краткое объяснение того, что делает сценарий или функция. Одна или несколько строк. .DESCRIPTION Более детальное объяснение того, что делает сценарий или функция. Используйте столько строк, сколько нужно. .PARAMETER computername После точки и ключевого слова следует имя параметра. Раздел содержит объяснение назначения параметра. Каждому параметру сценария или функции можно выделить по одному такому разделу: .PARAMETER filePath .EXAMPLE Нет нужды нумеровать примеры. .EXAMPLE PowerShell будет автоматических их нумеровать при отображении текста для пользователя. #>

Этот пример включает четыре самых часто используемых ключевых слов с точкой. Windows PowerShell не различает регистра букв ключевых слов, хотя в документации они приводятся всеми заглавными (поэтому я привожу их именно в этом варианте). Использование только заглавных букв позволяет выделить разделы в общем объеме кода.

Другой замечательный раздел — LINK. Здесь можно указать начинающийся с «http://» URL-адрес онлайновой версии справки. Если разместить справку в интрасети, пользователи смогут получить больше информации, например больше примеров, более подробные контактные данные и т. п.

Windows PowerShell также генерирует дополнительную справочную информацию на основе анализа вашего сценария или функции. Оболочка определяет имя, базовый синтаксис (в том числе имена параметров и типы данных), а также другую информацию. При этом закодированные для параметра значения по умолчанию не определяются:

Param($computername = 'localhost')

Поэтому нужно указать в справке все значения по умолчанию в самом параметре или даже в описании.

Основанная на комментария красота

Еще одно преимущество справки на основе комментариев заключается в том, что на самом деле она предоставляет два вида справочных сведений. Первый вид сведений предназначается для тех, кто выполняет команду help в ваших сценариях и функциях, а второй — тем, кто читает ваши сценарии.

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

Дон Джонс (Don Jones) — носит звание MVP и является автором «Learn Windows PowerShell in a Month of Lunches» (Manning Publications Co., 2011), книги, призванной помочь каждому администратору освоить Windows PowerShell. Дон читает общедоступные и интерактивные курсы по Windows PowerShell. Связаться с ним можно связаться через его веб-сайт ConcentratedTech.com.