about_comment_based_help

РАЗДЕЛ
    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 
            Добавление расширения имени файла к переданному на вход имени.

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

            .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 формирует имя в соответствии с датой 
                   и временем запуска и сохраняет выходные данные в 
                   локальном каталоге.
        
                   Требуется?                    false
                   Позиция?                      1
                   Значение по умолчанию                
                   Принимать входные данные 
                   с конвейера?                  false
                   Принимать подстановочные знаки?  

               <CommonParameters>
                   Данный командлет поддерживает общие параметры: 
                   -Verbose, -Debug, -ErrorAction, -ErrorVariable, 
                   -WarningAction, -WarningVariable, -OutBuffer и 
                   -OutVariable. Чтобы получить дополнительные 
                    сведения, введите команду "get-help 
                    about_commonparameters".
    
            ВХОДНЫЕ ДАННЫЕ
                   Нет. Объекты не могут передаваться скрипту 
                   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)





Показ: